Research Note
Coding Agent Instruction Placement Framework
An instruction file is context, not enforcement. Put a constraint in the weakest layer that remains reliable enough for its consequence.
In this article
Coding Agent Instruction Placement Framework
Placement principle
An instruction file is context, not enforcement. Put a constraint in the weakest layer that remains reliable enough for its consequence.
| Constraint | Durable layer | Why |
|---|---|---|
| Repeated workflow or codebase convention | Scoped project rule | Helps the agent find the expected path |
| One task's outcome and exclusions | Task plan or prompt | Keeps temporary scope out of global rules |
| Architecture decision | Versioned decision record and code structure | Preserves rationale for people and tools |
| Formatting requirement | Formatter or linter | Automatically detects violations |
| Required behavior | Test, type, schema, or invariant | Turns prose into executable evidence |
| Access restriction | Permission, sandbox, policy, or approval | Prevents rather than requests |
| Release requirement | CI gate and protected workflow | Keeps acceptance independent from generation |
Rule-writing method
Collect repeated corrections from real work. Remove preferences that do not change outcomes. Write one rule around one scope. Include the command to run, the canonical file or example, and the evidence expected after a change.
Reference canonical files instead of copying long style guides. Version project rules with the repository. Test them on a representative task and inspect whether they were actually applied.
Current Cursor boundary
Cursor's January 2026 guide describes static rules in .cursor/rules/ and advises teams to keep them focused, reference canonical examples, avoid copying whole style guides, and add rules after repeated mistakes appear.
Format and product behavior can change. The broader placement principle remains product-neutral.
Failure modes
A large rule file becomes stale and consumes useful context. Vague directions such as "write high-quality code" are not testable. Security restrictions written only as prose can be ignored. Conflicting instructions create ambiguity instead of control.
Move enforceable requirements into code, tests, schemas, permissions, CI, or policy.
Sources
Follow the evidence.
- csrc.nist.gov: finalcsrc.nist.gov
- cursor.com: agent best practicescursor.com
- cursor.com: teamscursor.com
- cursor.com: 1 7cursor.com
- cursor.com: data usecursor.com
- cursor.com: auto reviewcursor.com
- cursor.com: securitycursor.com
- cursor.com: privacycursor.com
- daltonanderson.ghost.io: how i built a go app in 4 hours with cursor aidaltonanderson.ghost.io
- git-scm.com: v2git-scm.com
- go.dev: getting startedgo.dev
- Spotify episodeopen.spotify.com
- owasp.org: www project top 10 for large language model applicationsowasp.org
- owasp.org: www project code review guideowasp.org
- slsa.dev: v1.2slsa.dev
- daltonanderson.net: how i built a go app in 4 hours with cursor aidaltonanderson.net
- youtu.be: n4 J1tDwreMyoutu.be