TocoAI Tips & Tricks

Name: TocoAI
Author: TocoAI

1. Session Management

🔁 1. Double-click a message to roll back the session context

Double-clicking a previous message rolls the session context back to that point in time
Use cases: AI went in the wrong direction, you want to redo a design decision, or you made a mistake and want to undo it

📏 2. Keep an eye on the context usage percentage

The UI shows the current context usage percentage — once it crosses the red line, the AI’s memory and output quality will noticeably degrade
It’s recommended to wrap up proactively when you reach 70%–80%: ask the AI to summarize key conclusions, unfinished items, and design decisions, then start a new session to continue
Typical prompt: “Please summarize the current session’s progress, key design decisions, and outstanding issues so I can continue in a new session.”

🎯 3. One session, one task

Keep each session focused on one clear task (e.g., implementing a few APIs, completing the modeling for a module)
Mixing multiple tasks in a single session leads to context bloat, scattered AI attention, and conflicting decisions
For ad-hoc minor requests, prefer opening a new session rather than embedding them in the current one

🪟 4. Use sub-sessions to batch-process backlog items

In the workbench, batch-select APIs (no more than 5 per batch recommended) and add them to the same new session for execution
Complex APIs should have dedicated sessions; simple CRUD APIs can be grouped together
Sub-sessions are fully independent and do not share context with each other

2. Providing Precise Context

📎 5. Use @Files to reference specific files

Type @Files in the chat input to reference specific code files in your project — the AI will read the file content directly as context
Use case: “@Files MemberController.java — the return value of this API needs an additional xxx field”
Advantage: No manual copy-pasting, precise file targeting, prevents the AI from guessing or reading the wrong file

🧩 6. Use @Toco Design Element to reference specific design elements

Type @Toco Design Element in the chat input to reference specific design elements in your project (e.g., a DTO, VO, API, read plan, write plan, etc.)
Use case: “@Toco Design Element MemberBaseDto — please analyze which fields are missing from this DTO”
Advantage: Pulls the structural definition of the design element directly, making the AI’s suggestions more accurate and avoiding field name mismatches

✂️ 7. Select a code snippet to provide focused context

Select a piece of code in the editor before starting a conversation — the AI will use that snippet as the precise context for analysis or modification
Use cases: Adding comments to a method, refactoring a logic block, investigating a bug
Advantage: Compared to pasting the entire file, selecting a snippet saves a significant amount of context space and keeps the AI focused on what actually needs attention

💡 8. Combining all three methods works best

Understand structure broadly → use @Toco Design Element to reference design elements
Locate a specific file → use @Files to reference code files
Fine-grained operations → select a specific code snippet
Combined example: “@Toco Design Element MemberBaseDto @Files MemberBOService.java — the current registration logic is missing member level initialization, please add it”

3. Working with Design Elements

✏️ 9. Two ways to modify modeled content

Option 1 (Chat-based modification): Describe the change in the chat window and the AI handles it automatically — great for quick adjustments
Option 2 (Manual design page editing): Edit design elements directly on the design page — better for fine-grained adjustments and bulk field editing
💡 Both approaches can be combined: use chat to model quickly, then open the design page to fine-tune details

🔍 10. The design page is the single source of truth for your code

For the framework code generated by Toco (FULLY_LOCKED sections), reading the design elements is far more efficient than reading the code itself
If you want to know what fields a DTO has or what the parameter structure of an API looks like, opening the corresponding design element page is 10× faster than digging through the code

🧩 11. Always regenerate code after modifying design elements

After manually modifying a design element on the design page, you must trigger a code regeneration — otherwise the code and the design will be out of sync
When design elements are modified through chat, the AI triggers code generation automatically; after manual edits, remember to notify the AI or trigger regeneration yourself

📐 12. Use @XxxAgent to directly assign the executor

If you know exactly what needs to be done and who should do it, use @AgentName in your message to assign directly
@DomainArchitect → Modeling, Entity/Relation modifications
@PlannerAgent → Planning & analysis, code reading
@DesignerAgent → Design element operations: DTO/VO/API/write plans/read plans, etc.
@DeveloperAgent → Code writing, file modifications
Bypasses automatic AI scheduling, reduces unnecessary intermediate steps, and speeds up execution

4. Describing Requirements

📋 13. The more specific your requirement, the higher the output quality

When describing a requirement, try to include: business context + specific feature points + boundary conditions + special rules
Avoid vague statements like “build a user management module” — instead say: “Build a user management module with three APIs: registration (phone number + password), login (returns a JWT Token), and query current user info. Phone numbers must be unique at registration.”
When you have mockups, interaction docs, or a PRD, paste or upload them directly — the AI can extract API and field information from them

🖼️ 14. Make good use of image input

You can directly upload UI mockups, ER diagrams, and flowcharts — the AI can recognize fields, relationships, and business processes from the images
After uploading, add a brief note such as: “Please analyze the required APIs and fields based on this mockup” for better results

🔄 15. Interface analysis results can be iteratively revised before confirming

The output of analyzeInterfaceFromRequirement is not final (it’s part of the requirement decomposition flow) — you can continue the conversation to make adjustments
Typical prompts: “The return value of API #3 also needs to include the xxx field”, “Merge APIs #1 and #2 into one”
Confirm execution only when you’re satisfied, to avoid having to repeatedly revise design elements later

5. Code Quality & Security

🔒 16. Respect the FULLY_LOCKED annotation — never modify it manually

Classes and methods annotated with @TocoGenerated(lockLevel = FULLY_LOCKED) are core framework code
Manually modifying them will cause your changes to be overwritten the next time code is regenerated
To extend behavior, locate the corresponding SIGNATURE_LOCKED extension point (e.g., validateAggregate, postProcessData)

🧪 17. Write business validations in the BO’s validateAggregate method

The framework automatically calls validateAggregate() before every write operation — this is the safest place to enforce business invariants
Examples: balance cannot be negative, state transition validity checks, required field non-null checks
Avoid duplicating validations in the Controller or Service — centralize them in the BO

🌉 18. Cross-module calls must go through public_service interfaces

Direct injection of another module’s Service is forbidden — all cross-module calls must go through RPC interfaces defined in public_service
Violating this rule creates hard dependencies between modules and undermines the ability to split into microservices

6. Productivity Tips

📦 19. Use the workbench to manage multiple pending tasks

After interface analysis is complete, save all APIs to the workbench first, then select and execute them in batches
The workbench is the “dispatch center” for multi-session task management — it prevents overloading a single session with too many tasks

🗂️ 20. The .toco/rules file is where team standards accumulate

Write your team’s coding conventions, naming rules, authentication requirements, and prohibited patterns into the rules file
Configure once — all sessions and all team members’ AI behavior will automatically follow these rules
For new team members, the rules file is also the fastest way to get up to speed on team standards

🔁 21. When the AI is interrupted, use “continue” to resume — don’t start over

If the AI’s execution is manually interrupted or stops due to an error, just say “continue” — the AI will check what has already been completed and resume from the breakpoint
Don’t say “redo everything from scratch” — this will cause already-completed design elements or code to be duplicated

🧵 22. For complex tasks: model first, then design, then code — don’t skip steps

Correct order: DomainArchitect modeling → PlannerAgent planning → DesignerAgent design elements → code generation → DeveloperAgent coding
Skipping modeling and going straight to coding means Entity/DTO/BO infrastructure won’t exist, and DeveloperAgent won’t be able to implement the business logic correctly
Skipping design elements and going straight to coding causes structural mismatches between framework-generated code and hand-written code, making future maintenance difficult

7. Debugging & Troubleshooting

💬 23. Paste error messages directly into the chat

When you encounter a compilation error or runtime exception, paste the complete error stack trace directly into the chat
This is far more effective than saying “there’s an error” — the AI can pinpoint the problem immediately

🗑️ 24. Use rollback instead of “undo”

When the AI makes an unexpected design change, double-clicking to roll back is more reliable than asking the AI to undo it step by step
Undo operations (e.g., “remove the field you just added”) are prone to omissions — rolling back the session context is more thorough