How to Structure a Codebase for AI Coding Agents

TL;DR

Organize each codebase around three focused directories: AI docs for persistent knowledge, specs for implementation plans, and a tool-specific folder such as .claude for reusable prompts. This structure helps coding agents load relevant context, resume work after context resets, execute larger planned tasks, and reuse validated workflows across sessions and compatible AI coding tools.

Transcript

What's up engineers? Indydev Dan here. Imagine opening your codebase and having your AI coding tool instantly understand your codebase better and faster than you can read the readme. There are three simple folders that can unlock that superpower for you in every project you touch. We're going to break them down into their atoms so you can use them ... Read More

Key Insights

• Context is the foundation of effective AI coding because an agent cannot use project information it cannot access. A deliberate repository structure makes critical knowledge easier to discover and reduces the need to reconstruct the same context manually during every new session.
• The AI docs directory is a persistent knowledge repository for coding agents. It can contain third-party API documentation, integration details, codebase-specific conventions, implementation notes, and other reference material that helps an agent understand how the project should be developed.
• The specs directory is where planned work is defined before implementation begins. Detailed specifications can function as prompts for agentic coding tools, giving them enough direction to build features or larger codebases through coordinated tool use and self-validating execution loops.
• The plan is the prompt in the presented workflow. Stronger plans provide stronger implementation context, while repeated conversational prompting can limit the amount of work delegated in one pass. The recommended sequence is to think carefully, document the plan, and then let the agent build.
• Reusable prompts are stored as repository commands, with .claude/commands shown as one tool-specific implementation. Although the directory name and command mechanism may vary, the underlying prompts can be adapted for Claude Code, Codex, Cursor, and other AI coding tools.
• Context priming is a reusable startup process that instructs an agent to inspect important project files, such as the README and repository tree. It prepares a fresh coding session to locate relevant files and concepts before implementation work starts.
• AI coding sessions eventually require resets because model context windows are limited. Persistent documentation, specifications, and reusable priming commands make it easier to start new sessions without manually repeating all prior project orientation and workflow instructions.
• Plan drafting is a collaborative planning technique in which the coding agent produces the first specification draft after reading the repository. The engineer supplies the feature goal and requested sections, while the agent uses its codebase inspection to propose implementation details for review.

Questions & Answers

Q: How should a codebase be structured for AI coding agents?

A codebase can be organized around three focused directories: AI docs, specs, and a reusable prompt directory such as .claude. AI docs store persistent project knowledge, specs define planned implementation work, and the prompt directory contains repeatable commands. Together, they help an agent discover relevant information, understand intended changes, and repeat useful workflows across sessions.

Q: What should go inside an AI docs directory?

An AI docs directory should contain information that coding agents need repeatedly, including third-party API documentation, integration details, custom implementation patterns, project conventions, and codebase-specific notes. Its purpose is to act as persistent memory that an agent can read quickly, reducing the need to search for or reintroduce the same reference material in each session.

Q: Why is a specs directory important for agentic coding?

A specs directory stores the detailed plans that guide delegated engineering work. In the presented approach, a specification is effectively the prompt given to the coding agent. A comprehensive plan can describe the desired feature, relevant constraints, and validation process, allowing an agentic tool to perform more coordinated work than a sequence of small, iterative prompts.

Q: What does 'the plan is the prompt' mean in AI coding?

The phrase means that the quality and completeness of an implementation plan directly shape the coding agent's instructions. Rather than relying on repeated conversational corrections, the engineer writes a detailed specification that defines the work before execution. The agent can then use that document as its main operational context while inspecting files, using tools, implementing changes, and validating results.

Q: How does context priming help an AI coding agent?

Context priming gives a fresh agent session a repeatable set of instructions for understanding a repository. The demonstrated command reads important files, including the README, and inspects the project tree. It then produces a project summary so the agent knows where key files and concepts are located before beginning implementation, review, or planning work.

Q: Can reusable coding prompts work outside Claude Code?

Reusable prompts are not inherently limited to Claude Code, even though .claude/commands is the demonstrated implementation. The same underlying instructions can be adapted for Codex, Cursor, or another AI coding assistant. Directory names and invocation methods may differ, but the reusable pattern remains the same: store, validate, improve, and rerun useful prompts across sessions.

Q: What is plan drafting in an agentic coding workflow?

Plan drafting is a collaborative process in which the AI coding tool creates the first version of a feature specification. The engineer provides the goal, identifies relevant commands or components, and requests a structure for the plan. After reading the codebase, the agent drafts the specification, which the engineer can inspect and refine before authorizing implementation work.

Q: How were the three directories applied to Pocket Pick?

The demonstration uses Pocket Pick, a small MCP server backed by a SQLite database, to plan support for user-provided IDs in the add and add-file operations. A reusable command first primes the agent with repository context. The agent is then asked to draft a specification for the feature, combining stored project knowledge, explicit planning, and reusable prompts.

Summary & Key Takeaways

• The proposed structure gives coding agents three distinct sources of context. AI docs preserve third-party documentation, integration details, conventions, and implementation notes. Specs contain detailed plans for delegated work. A prompt directory, demonstrated through .claude commands, stores reusable instructions that can initialize sessions or automate recurring engineering workflows.

• Planning is presented as the central mechanism for scaling agentic coding. Instead of repeatedly prompting an assistant through small decisions, engineers can create a comprehensive specification and hand it to an agent capable of using tools and following self-validating loops. Plan drafting further divides the planning process between the engineer and the coding agent.

• The Pocket Pick demonstration applies the structure to a proposed feature that would accept custom IDs when adding stored knowledge items. The agent first runs a reusable context-priming command, then begins drafting a specification after inspecting the repository. This illustrates how persistent documentation, explicit plans, and reusable prompts can support practical feature development.