agents-create

Include only what genuinely helps, ruthlessly cut everything else. These principles apply regardless of language or framework — C#, Python, TypeScript all follow the same rules.

Core Principles

• Minimum viable requirements. Ask of each line: "Does this earn its cost on nearly every session?" If not, cut it. Every line loads on every session — brevity has direct cost benefits.
• Two failure modes. (1) Length — as instruction count grows, compliance degrades uniformly, not just for new instructions. (2) Task-irrelevant requirements — correct instructions not needed for the current task still get followed, increasing cost and reducing success.
• Don't send an LLM to do a linter's job. Style guidelines add instructions and irrelevant context. Use actual linters, wired to hooks if the harness supports it.
• Never auto-generate. Auto-generated files are stuffed with documentation the agent can read directly. Write by hand.
• Architecture and overview sections have weak evidence in root files. Exception: scoped sub-files can carry richer context — they only load when the agent is already working in that area.

Single File vs. Hierarchical System

Single root file for simple projects: one app, one language, one team. Keep it under 100 lines.

Hierarchical system for monorepos, large codebases, or multiple apps/packages/services. The harness auto-loads AGENTS.md files as the agent navigates — apps/web/AGENTS.md only loads when the agent works there.

Hierarchical Rules

Place files at semantic boundaries — where responsibilities shift or contracts matter. Not in every directory.