Start With A Router, Not A Manual
A coding agent is not just a chatbot that writes code. It can read files, edit files, run terminal commands, call tools, and sometimes hand work to sub-agents. That extra power makes the first prompt less important than the starting context. If the agent begins with a vague request and no map, it will spend its limited context window guessing what matters.
Create an `AGENTS.md` or `CLAUDE.md` at the project root. Think of it as a router: a short file that tells the agent where to look, what rules matter, and what it may or may not touch. Keep it lean. Do not paste your whole architecture history into it. A useful root file might include the project purpose, primary tech stack, common commands, testing expectations, dangerous areas, and links to deeper files such as `docs/architecture.md`, `docs/api.md`, or `frontend/AGENTS.md`.
The failure mode is trying to solve context with one giant instruction file. Large files get stale, bury the important rules, and waste the agent's attention before it even sees the task. Use the root file as an inventory and navigation layer. The goal is not to preload everything. The goal is to help the agent choose the right next file.
Write Rules That Prevent Real Mistakes
Once the agent can orient itself, give it rules that shape its actions. Rules are not personality preferences. They should protect the project from failures you can predict: editing generated files, changing database migrations casually, skipping tests, touching client data, or mixing unrelated work in one change. Good rules are short, concrete, and tied to observable behavior.
For example: `Do not edit files in generated/`; `Run npm test for frontend changes`; `Do not change public API names without updating docs/api.md`; `Never combine records across clients`; `Ask before running commands that modify production data`. These instructions matter because tools give the agent reach. A tool is any capability outside plain text generation: file search, file editing, shell commands, browser automation, API calls, MCP servers, or custom scripts. MCP, short for Model Context Protocol, is a common way to connect agents to external tools and data sources.
Some rules belong in prose. Others should become deterministic checks. If a mistake is serious and easy to detect, use a hook, script, or CI check instead of relying only on instruction. A pre-tool hook can block edits to a protected directory. A pre-push check can scan for secrets or sensitive data. The practical pattern is simple: write a rule after you observe a failure, then promote it to automation when the cost of missing it is high.
Add Folder Indexes So The Agent Can Drill Down
After the root file and rules, make the project easier to navigate. Agents read only a slice of your repo at a time. A folder index gives them a cheap way to decide where to spend that attention. Add small `index.md` files inside important directories, especially where filenames alone do not explain the system.
An index should answer the questions a newcomer would ask: what lives here, what should be edited here, what depends on it, and where to go next. For a docs or knowledge folder, use cross-links. For a code folder, list the main entry points, test locations, and ownership boundaries. A simple pattern is to separate raw inputs, structured knowledge, and outputs, but the exact folder names matter less than consistent navigation.
This approach is often more reliable than dumping everything into semantic search. Search is useful when the dataset is huge or keyword matching fails, but a structured drill-down path works well for first-time agent use. It also keeps noisy context out of the task. Save durable decisions, architecture notes, and workflow rules as evergreen context. Keep Slack threads, meeting fragments, and one-off notes separate unless they have been summarized into something the agent can trust.
Promote Repeated Work Into Skills, Then Agents
Once your project map works, you will notice repeated requests: run the test suite and summarize failures, add an endpoint in the house style, update docs after a schema change, review a pull request, or prepare a release note. Do not keep re-explaining those workflows in chat. Turn them into skills: reusable instructions with inputs, steps, expected outputs, and verification.
A skill is still judgment-based. It tells the agent how to perform a recurring workflow, but the agent may need to inspect the situation and adapt. Keep skills in files the root router points to, such as `skills/test-debugging.md` or `docs/workflows/release.md`. Include the commands to run, what success looks like, common failure cases, and when to stop and ask. Before automating a skill on a schedule or behind a button, run it manually enough times to see whether the output is reliable.
Sub-agents come later. A sub-agent is a delegated worker with a narrower role, such as code reviewer, test fixer, documentation updater, or migration checker. They are useful when the responsibility is stable and separable. Creating too many early creates maintenance work and conflicting advice. Start with project context, then skills, then sub-agents only when the role has proved itself.
Keep The Map Alive
Project context decays. Commands change, APIs move, models behave differently, and workflows that once needed long instructions may later need shorter ones. Treat `AGENTS.md`, folder indexes, skills, hooks, and sub-agent definitions as maintained infrastructure, not a one-time setup.
Add a small review note somewhere visible, even a `docs/context-rot.md`. List the files that guide agents and how often to check them. Root identity files should change slowly. Folder indexes need updates when structure changes. Skills need review when repeated work starts failing or becomes overexplained. Tool and MCP instructions need checks when providers change APIs, auth, or naming conventions.
The central habit is to make the agent's starting map match the real project. A first-time coding agent user does not need a complicated agentic operating system. They need a lean router, a few hard rules, navigable folders, and repeatable workflows. With that in place, asking for code becomes less like handing a stranger a vague task and more like bringing a new teammate to the right desk with the right checklist.
Key takeaways
- Use `AGENTS.md` or `CLAUDE.md` as a short project router, not a giant manual.
- Write concrete rules around real risks: protected files, test commands, data boundaries, and commands that need approval.
- Add folder-level `index.md` files so the agent can find relevant context without reading the whole repo.
- Turn repeated prompts into reusable skills before turning them into automations or sub-agents.
- Use hooks, scripts, or CI checks for mistakes that are serious and mechanically detectable.
- Review agent context regularly because rules, tools, APIs, and model behavior all drift.