Start With A Router, Not A Rule Dump
The central idea is simple: your first agent-friendly project should make the right thing easy for the agent to find. A coding agent is not just a chat window. It can read files, edit files, run terminal commands, and sometimes call outside tools. That power helps only if the project tells the agent what matters before it starts changing code.
Create an `AGENTS.md`, `CLAUDE.md`, or similar file at the project root. Keep it short. Treat it as a router, not a manual. It should tell the agent what this project is, where the important files live, what commands verify work, and what rules must never be broken. If you put every decision, style rule, meeting note, and exception in one file, you fill the agent's context window with noise. Context is the limited working memory the model uses while reasoning. Spend it on directions, not archives.
A useful first version might include: project goal, stack, install command, test command, formatter command, main folders, coding style, and a short list of hard constraints. For example: "Do not edit `migrations/` without asking," "Use existing UI components from `src/components/ui`," and "Run `npm test` before claiming a bug is fixed." Link to deeper files only when needed, such as `docs/architecture.md`, `docs/api.md`, or `docs/decisions.md`.
Separate Stable Context From Noisy Context
Once the root file points the way, the next job is deciding what belongs behind those links. Agents perform better when stable knowledge is separated from raw chatter. Stable context includes product goals, architecture decisions, naming conventions, testing expectations, and known traps. Noisy context includes long Slack threads, issue debates, logs, and copied research. Both can be useful, but they should not live in the same place.
Make a small `docs/context/` folder. Add files like `project-overview.md`, `architecture.md`, `coding-rules.md`, and `verification.md`. Each file should answer questions the agent will actually ask while working: What is this app trying to do? Which modules own which responsibilities? What patterns should new code follow? How do we know a change worked? If the project is small, these files can be short. A dozen accurate lines beat a long document the agent has to sift through.
Avoid building a complex knowledge system on day one. Keyword-friendly markdown with clear headings is usually enough. Index files and cross-links are more reliable for a beginner project than embeddings, semantic search, or knowledge graphs. Those advanced methods help when the information is huge or relationships are complicated. For your first setup, optimize for readable drill-down paths: root router, then focused files, then source code.
Turn Repeated Work Into Skills Later
After the agent has rules and context, you can start noticing repeated workflows. A skill is a reusable instruction set for a task that is common but still requires judgment. Examples include "add a new API endpoint," "write a regression test," "prepare a pull request summary," or "run the app and inspect errors." Skills are useful because they stop you from re-explaining the same process in every chat.
Do not create ten skills before the project has real usage. Start by writing ordinary instructions in `AGENTS.md` and project docs. When you see the same workflow succeed three or four times, promote it into a separate file like `docs/skills/add-endpoint.md`. Include the checklist, expected commands, common mistakes, and what the agent should report back. Keep it practical: inputs, steps, verification, output.
This also prevents maintenance debt. Agent instructions rot. Models change behavior, dependencies change commands, APIs change names, and your team changes its preferences. Put a small `docs/rot.md` or maintenance note in the project that says which files need review and how often. Root identity and project goals change slowly. Skills and tool instructions change more often. Sub-agent roles change fastest because they depend heavily on model behavior and team workflow.
Use Tools And Verification Deliberately
A tool is anything the agent can call outside its own text generation: reading files, editing files, running tests, searching the repo, using a CLI, calling an API, or connecting through MCP. MCP, or Model Context Protocol, is a standard way for an agent to connect to external systems such as GitHub, databases, docs, or internal services. For a beginner project, the important point is not the protocol. It is that every powerful tool needs boundaries.
Write down which commands are safe and expected. For example: `npm test`, `npm run lint`, `npm run typecheck`, `pytest`, or `cargo test`. Also write down what requires permission: deleting files, editing generated code, changing database migrations, pushing to GitHub, touching secrets, or modifying production configuration. If your agent platform supports hooks, use them for deterministic guardrails. A hook is a rule enforced by the environment, such as blocking edits to a protected folder or scanning for private data before a commit.
Verification is the difference between an agent that sounds confident and one that actually helped. Tell the agent what counts as done. A small change might require a focused test. A risky change might require tests, linting, and a second review pass. You can use another model, a code review tool, system logs, or the local test suite as the verifier. The pattern matters more than the tool: spec the task, let the agent change the environment, then check the result with something more objective than its own summary.
Add Sub-Agents Only After The Role Is Clear
Sub-agents are separate agent workers assigned to smaller tasks. One might inspect tests while another reads the API layer. In advanced setups, people run many agents in parallel using cloud environments or Git worktrees so they do not overwrite each other. A worktree is a separate checkout of the same repository, useful when multiple changes need to happen at once without file conflicts.
For your first agent-friendly project, sub-agents should come last. If the main agent does not have clear project rules, sub-agents will multiply confusion. Start with one agent and good instructions. When a responsibility becomes stable, such as "review this change for security issues" or "summarize this subsystem before editing," then write that role down and use it consistently. A sub-agent is worth creating when it has a clear input, a bounded output, and a verification step.
The project you are building is not a dashboard of agent tricks. It is a small operating system for useful work: a lean root file, focused context, reusable workflows, safe tools, and verification. That is enough for a first coding agent to make real edits without inventing the rules as it goes. When the environment tells the agent where to look, what not to touch, and how success is checked, you move from prompting harder to setting up better work.
Key takeaways
- Use `AGENTS.md` as a short router to project rules, commands, context files, and hard constraints.
- Keep stable project knowledge separate from noisy threads, logs, and raw research.
- Promote repeated workflows into skill files only after they have proven useful several times.
- Define safe tools, permission boundaries, and verification commands before asking for larger edits.
- Add sub-agents after roles stabilize, not before the main agent has clear instructions.