diff --git a/ai/references/a-complete-guide-to-agents.md.md b/ai/references/a-complete-guide-to-agents.md.md new file mode 100644 index 0000000..711c8d7 --- /dev/null +++ b/ai/references/a-complete-guide-to-agents.md.md @@ -0,0 +1,290 @@ +--- +source: https://www.aihero.dev/a-complete-guide-to-agents-md +--- + +# A Complete Guide To AGENTS.md + +Have you ever felt concerned about the size of your `AGENTS.md` file? + +Maybe you should be. A bad `AGENTS.md` file can confuse your agent, become a +maintenance nightmare, and cost you tokens on every request. + +So you'd better know how to fix it. + +## What is AGENTS.md? + +An `AGENTS.md` file is a markdown file you check into Git that customizes how AI +coding agents behave in your repository. It sits at the top of the conversation +history, right below the system prompt. + +Think of it as a configuration layer between the agent's base instructions and +your actual codebase. The file can contain two types of guidance: + +- **Personal scope**: Your commit style preferences, coding patterns you prefer +- **Project scope**: What the project does, which package manager you use, your + architecture decisions + +The `AGENTS.md` file is an open standard supported by many - though not all - +tools. + +
+ CLAUDE.md + +Notably, Claude Code doesn't use `AGENTS.md` - it uses `CLAUDE.md` instead. You +can symlink between them to keep all your tools working the same way: + +```bash +# Create a symlink from AGENTS.md to CLAUDE.md +ln -s AGENTS.md CLAUDE.md +``` + +
+ +## Why Massive `AGENTS.md` Files are a Problem + +There's a natural feedback loop that causes `AGENTS.md` files to grow +dangerously large: + +1. The agent does something you don't like +2. You add a rule to prevent it +3. Repeat hundreds of times over months +4. File becomes a "ball of mud" + +Different developers add conflicting opinions. Nobody does a full style pass. +The result? An unmaintainable mess that actually hurts agent performance. + +Another culprit: auto-generated `AGENTS.md` files. Never use initialization +scripts to auto-generate your `AGENTS.md`. They flood the file with things that +are "useful for most scenarios" but would be better progressively disclosed. +Generated files prioritize comprehensiveness over restraint. + +### The Instruction Budget + +Kyle from Humanlayer's +[article](https://www.humanlayer.dev/blog/writing-a-good-claude-md) mentions the +concept of an "instruction budget": + +> Frontier thinking LLMs can follow ~ 150-200 instructions with reasonable +> consistency. Smaller models can attend to fewer instructions than larger +> models, and non-thinking models can attend to fewer instructions than thinking +> models. + +Every token in your `AGENTS.md` file gets loaded on **every single request**, +regardless of whether it's relevant. This creates a hard budget problem: + +| Scenario | Impact | +| -------------------------- | ----------------------------------------------------- | +| Small, focused `AGENTS.md` | More tokens available for task-specific instructions | +| Large, bloated `AGENTS.md` | Fewer tokens for the actual work; agent gets confused | +| Irrelevant instructions | Token waste + agent distraction = worse performance | + +Taken together, this means that **the ideal `AGENTS.md` file should be as small +as possible.** + +### Stale Documentation Poisons Context + +Another issue for large `AGENTS.md` files is staleness. + +Documentation goes out of date quickly. For human developers, stale docs are +annoying, but the human usually has enough built-in memory to be skeptical about +bad docs. For AI agents that read documentation on every request, stale +information actively _poisons_ the context. + +This is especially dangerous when you document file system structure. File paths +change constantly. If your `AGENTS.md` says "authentication logic lives in +`src/auth/handlers.ts`" and that file gets renamed or moved, the agent will +confidently look in the wrong place. + +Instead of documenting structure, describe capabilities. Give hints about where +things _might_ be and the overall shape of the project. Let the agent generate +its own just-in-time documentation during planning. + +Domain concepts (like "organization" vs "group" vs "workspace") are more stable +than file paths, so they're safer to document. But even these can drift in +fast-moving AI-assisted codebases. Keep a light touch. + +## Cutting Down Large `AGENTS.md` Files + +Be ruthless about what goes here. Consider this the absolute minimum: + +- **One-sentence project description** (acts like a role-based prompt) +- **Package manager** (if not npm; or use `corepack` for warnings) +- **Build/typecheck commands** (if non-standard) + +That's honestly it. Everything else should go elsewhere. + +### The One-Liner Project Description + +This single sentence gives the agent context about _why_ they're working in this +repository. It anchors every decision they make. + +Example: + +```markdown +This is a React component library for accessible data visualization. +``` + +That's the foundation. The agent now understands its scope. + +### Package Manager Specification + +If you're In a JavaScript project and using anything other than npm, tell the +agent explicitly: + +```markdown +This project uses pnpm workspaces. +``` + +Without this, the agent might default to `npm` and generate incorrect commands. + +
+ Corepack is also great +You could also use [`corepack`](https://github.com/nodejs/corepack) to let the system handle warnings automatically, saving you precious instruction budget. +
+ +### Use Progressive Disclosure + +Instead of cramming everything into `AGENTS.md`, use **progressive disclosure**: +give the agent only what it needs right now, and point it to other resources +when needed. + +Agents are fast at navigating documentation hierarchies. They understand context +well enough to find what they need. + +#### Move Language-Specific Rules to Separate Files + +If your `AGENTS.md` currently says: + +```markdown +Always use const instead of let. +Never use var. +Use interface instead of type when possible. +Use strict null checks. +... +``` + +Move that to a separate file instead. In your root `AGENTS.md`: + +```markdown +For TypeScript conventions, see docs/TYPESCRIPT.md +``` + +Notice the light touch, no "always," no all-caps forcing. Just a conversational +reference. + +The benefits: + +- TypeScript rules only load when the agent writes TypeScript +- Other tasks (CSS debugging, dependency management) don't waste tokens +- File stays focused and portable across model changes + +#### Nest Progressive Disclosure + +You can go even deeper. Your `docs/TYPESCRIPT.md` can reference +`docs/TESTING.md`. Create a discoverable resource tree: + +``` +docs/ +├── TYPESCRIPT.md +│ └── references TESTING.md +├── TESTING.md +│ └── references specific test runners +└── BUILD.md + └── references esbuild configuration +``` + +You can even link to external resources, Prisma docs, Next.js docs, etc. The +agent will navigate these hierarchies efficiently. + +#### Use Agent Skills + +Many tools support "agent skills" - commands or workflows the agent can invoke +to learn how to do something specific. These are another form of progressive +disclosure: the agent pulls in knowledge only when needed. + +We'll cover agent skills in-depth in a separate article. + +## `AGENTS.md` in Monorepos + +You're not limited to a single `AGENTS.md` at the root. You can place +`AGENTS.md` files in subdirectories, and they **merge with the root level**. + +This is powerful for monorepos: + +### What Goes Where + +| Level | Content | +| ----------- | -------------------------------------------------------------------------- | +| **Root** | Monorepo purpose, how to navigate packages, shared tools (pnpm workspaces) | +| **Package** | Package purpose, specific tech stack, package-specific conventions | + +Root `AGENTS.md`: + +```markdown +This is a monorepo containing web services and CLI tools. +Use pnpm workspaces to manage dependencies. +See each package's AGENTS.md for specific guidelines. +``` + +Package-level `AGENTS.md` (in `packages/api/AGENTS.md`): + +```markdown +This package is a Node.js GraphQL API using Prisma. +Follow docs/API_CONVENTIONS.md for API design patterns. +``` + +**Don't overload any level.** The agent sees all merged `AGENTS.md` files in its +context. Keep each level focused on what's relevant at that scope. + +## Fix A Broken `AGENTS.md` With This Prompt + +If you're starting to get nervous about the `AGENTS.md` file in your repo, and +you want to refactor it to use progressive disclosure, try copy-pasting this +prompt into your coding agent: + +```txt +I want you to refactor my AGENTS.md file to follow progressive disclosure principles. + +Follow these steps: + +1. **Find contradictions**: Identify any instructions that conflict with each other. For each contradiction, ask me which version I want to keep. + +2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md: + - One-sentence project description + - Package manager (if not npm) + - Non-standard build/typecheck commands + - Anything truly relevant to every single task + +3. **Group the rest**: Organize remaining instructions into logical categories (e.g., TypeScript conventions, testing patterns, API design, Git workflow). For each group, create a separate markdown file. + +4. **Create the file structure**: Output: + - A minimal root AGENTS.md with markdown links to the separate files + - Each separate file with its relevant instructions + - A suggested docs/ folder structure + +5. **Flag for deletion**: Identify any instructions that are: + - Redundant (the agent already knows this) + - Too vague to be actionable + - Overly obvious (like "write clean code") +``` + +## Don't Build A Ball Of Mud + +When you're about to add something to your `AGENTS.md`, ask yourself where it +belongs: + +| Location | When to use | +| ------------------------- | -------------------------------------------------- | +| Root `AGENTS.md` | Relevant to every single task in the repo | +| Separate file | Relevant to one domain (TypeScript, testing, etc.) | +| Nested documentation tree | Can be organized hierarchically | + +The ideal `AGENTS.md` is small, focused, and points elsewhere. It gives the +agent just enough context to start working, with breadcrumbs to more detailed +guidance. + +Everything else lives in progressive disclosure: separate files, nested +`AGENTS.md` files, or skills. + +This keeps your instruction budget efficient, your agent focused, and your setup +future-proof as tools and best practices evolve. diff --git a/ai/references/my-agents.md-file-for-building-plans-you-actually-read.md b/ai/references/my-agents.md-file-for-building-plans-you-actually-read.md new file mode 100644 index 0000000..0d678cf --- /dev/null +++ b/ai/references/my-agents.md-file-for-building-plans-you-actually-read.md @@ -0,0 +1,69 @@ +# My AGENTS.md file for building plans you actually read + +Most developers are skeptical about AI code generation at first. It seems +impossible that an AI could understand your codebase the way you do, or match +the instincts you've built up over years of experience. + +But there's a technique that changes everything: the planning loop. Instead of +asking AI to write code directly, you work through a structured cycle that +dramatically improves the quality of what you get. + +This approach transforms AI from an unreliable code generator into an +indispensable coding partner. + +## The Plan Loop: A Four-Step Process + +Every piece of code now goes through the same cycle. + +![Plan Loop +Diagram](./my-agents.md-file-for-building-plans-you-actually-read/plan-loop-diagram.png) + +**Plan** with the AI first. Think through the approach together before writing +any code. Discuss the strategy and get alignment on what you're building. + +**Execute** by asking the AI to write the code that matches the plan. You're not +asking it to figure out what to build—you've already done that together. + +**Test** the code together. Run unit tests, check type safety, or perform manual +QA. Validate that the implementation matches what you planned. + +**Commit** the code and start the cycle again for the next piece. + +## Why This Matters + +This loop is completely indispensable for getting decent outputs from an AI. + +If you drop the planning step altogether, you're really hampering yourself. +You're asking the AI to guess what you want, and you'll end up fighting with +hallucinations and misunderstandings. + +Planning forces clarity. It makes the AI's job easier and your code better. + +## Rules for Creating Great Plans + +Here are the key rules from my `CLAUDE.md` file that make plan mode effective: + +```md +## Plan Mode + +- Make the plan extremely concise. Sacrifice grammar for the sake of concision. +- At the end of each plan, give me a list of unresolved questions to answer, if any. +``` + +These simple guidelines transform verbose plans into scannable, actionable +documents that keep both you and the AI aligned. + +Copy them into your `CLAUDE.md` or `AGENTS.md` file, and enjoy simpler, more +readable plans. + +Or, run this script to append them to your `~/.claude/CLAUDE.md` file: + +```bash +mkdir -p ~/.claude && cat >> ~/.claude/CLAUDE.md << 'EOF' + +## Plan Mode + +- Make the plan extremely concise. Sacrifice grammar for the sake of concision. +- At the end of each plan, give me a list of unresolved questions to answer, if any. +EOF +``` diff --git a/ai/references/my-agents.md-file-for-building-plans-you-actually-read/plan-loop-diagram.png b/ai/references/my-agents.md-file-for-building-plans-you-actually-read/plan-loop-diagram.png new file mode 100644 index 0000000..d31473b Binary files /dev/null and b/ai/references/my-agents.md-file-for-building-plans-you-actually-read/plan-loop-diagram.png differ