Why does a coding agent ignore project conventions?
Instructions kept only in chat can disappear from a new task’s context. Put concise guidance in the repository: real file paths, required checks and product decisions to preserve. Verify that the agent actually loads the applicable instructions.
How to check it
- Choose three concrete conventions from existing code instead of inventing a new architecture.
- Tie each rule to an observable outcome, such as form labels reachable by keyboard.
- Ask for one small change, then inspect the diff and test output for compliance.
Concrete example
Example: for an “Add a Save button” task, point to the current form component, the service that writes the data and the relevant test. If the agent introduces a second form framework, the guidance has not worked.
Avoid a false conclusion
A longer instruction file is not a cure. Fix contradictory, stale or unverifiable rules and never place credentials in it.
Reference
VCT Editorial