Best practices
Get better results with clear intent, good project setup, and the right mode for the task.
Do's and don'ts
| Do | Don't |
|---|---|
| Be specific: describe symptom, area, and context | Say "fix the bug" or "improve it" without context |
| Use Plan for big refactors, then Agent for implementation | Jump straight to Agent for large design changes |
| Run gates after changes and in CI | Merge without running gates |
| Put standards in AGENTS.md or .midcore/rules | Rely only on one-off chat instructions |
| Lock contracts before implementation when using the compiler | Start coding before contracts are frozen |
Be specific with intent
Instead of "fix the bug", describe the symptom and context:
- Good: "Fix the login bug where users see a blank screen after wrong credentials. Frontend is in apps/web."
- Weak: "Fix the bug"
Include file names, areas, or error messages when you have them. The agent uses this to narrow scope and avoid unrelated changes.
Use the right mode
| Mode | When to use |
|---|---|
| Agent | Implementation, multi-file edits, bug fixes with code changes |
| Plan | Design, migration strategy, architecture; no edits |
| Debug | Tracing failures, multiple hypotheses, targeted small fixes |
| Ask | Exploration, Q&A, docs only; no code changes |
Using Plan for big refactors and Agent for execution keeps scope under control and reduces rework.
Write useful AGENTS.md and rules
Put coding standards, preferred libraries, and "always run lint before commit" in AGENTS.md or .midcore/rules/. Short, actionable bullets work better than long essays. See Instructions & memory.
Keep contracts first
When using the Outcome Compiler, lock scope and contracts before implementation. Don’t skip to code; it keeps APIs and evidence aligned and avoids rework. See Outcome Compiler.
Run gates regularly
Run midcore gates run in CI and before releases. Evidence from gates is the proof you need for audit and compliance. Fix gate failures before merging.
CI
Scope creep
Verify after edits
Let the agent run lint and tests after making changes when your environment supports it. Fix new errors before moving on so they don’t pile up. Use Plan or smaller, focused tasks if the agent keeps introducing regressions.
Key takeaways
- Clear, specific intent (symptom, area, context) produces better scope and fewer unrelated edits.
- Use the right mode: Plan for design, Agent for implementation, Debug for failures, Ask for exploration.
- Contracts first and run gates regularly; verify after edits so errors don't pile up.
Related documentation
Common workflows · Extend Midcore · How Midcore works · CI/CD