Three Essential Directories for AI-Powered Codebases
Indydev Dan discusses three key directories that can significantly enhance the performance of AI coding tools within any project. These directories provide context and structure, allowing AI agents to understand and work with codebases more effectively. Regardless of whether you use Cursor, Windsor, Fline, Codeex, or Claude Code, these folders remain essential.
The Importance of Context
Context is paramount when using AI coding tools. If an AI agent lacks access to critical information, its ability to generate the desired output is severely limited. These three directories comprehensively and systematically address this issue.
1. AI Docs: The Persistent Knowledge Base
Function and Content
The AI Docs directory serves as a persistent memory or knowledge repository for AI coding tools. Think of it as the AI’s long-term memory. AI agents can instantly access the content within this folder. It should include:
-
Third-party API documentation.
-
Integration details.
-
Custom patterns and conventions used in the project.
-
Implementation notes specific to the codebase.
-
Anything else unique to the codebase.
Benefits
This directory allows for quicker ramp-up times when working with different codebases. It acts as a readily available database for AI agents, improving their understanding and efficiency.
2. Specs: The Blueprint for Agentic Coding
Specification as a Plan
The Specs directory is short for "specifications," which is synonymous with "plans." These plans detail the work to be done and are crucial for maximizing the output of AI coding tools. You can consider this directory your product requirement documents.
Scaling Compute with Detailed Plans
This directory is arguably the most important in the entire codebase. By writing comprehensive plans within the Specs directory, you can leverage agentic coding tools to accomplish significant tasks with a single prompt. Agentic coding allows for self-validating loops within prompts, enabling AI to execute complex operations.
Avoiding Iterative Prompting
Spending time planning upfront is more efficient than iteratively prompting back and forth with the AI. Detailed plans allow you to scale your compute and achieve more significant results in fewer steps. Remember, the plan is the prompt.
3. .claude (or Equivalent): Reusable Prompts
Purpose and Customization
The .claude directory, while named specifically for the Claw Code tool, represents a broader concept of storing reusable prompts. Although the example uses .claude, you can name this directory based on the AI tool you are using. This folder contains prompts that can be readily used across different sessions.
Context Priming for Efficiency
A critical reusable prompt to establish is the "context priming" prompt. This prompt instructs the AI coding tool (e.g., Claude Code, Codeex, Cursor) to gather information about the project, such as reading the README file and listing files in the directory.
Managing Context Windows
AI coding tools often have limited context windows (e.g., 200k to 1 million tokens). Context priming helps refresh the AI's understanding after it runs out of context, enabling it to continue working effectively.
Expanding Capabilities with Reusable Prompts
The .claude directory is not limited to context priming. You can also store prompts for other tasks, such as diff reviews or any other customized functionality. The capabilities are unlimited.
Practical Application: Building a Feature with Pocket Pick
The presenter demonstrates how these directories are used to add a new feature to a project called Pocket Pick. Pocket Pick stores and reuses code snippets using a simple SQLite database.
Implementing a New Feature
The new feature involves updating the add command to allow users to specify IDs when creating new pocket items. This enhancement improves search capabilities.
Utilizing the Three Directories
The presenter demonstrates how the AI Docs, Specs, and .claude directories are used to streamline the process:
- Context Priming: Claw Code is primed with a context priming prompt to understand the project's structure.
- Plan Drafting: Instead of writing the plan manually, Claw Code is instructed to create a first draft of the specification.
- Plan Review and Iteration: The draft plan is reviewed, tweaked, and refined.
- Implementation: The refined plan is then used to implement the new feature, with Claw Code automatically making the necessary code changes.
The Power of Agentic Coding
This example showcases the power of agentic coding, where the AI tool is not just generating code, but also planning, testing, and performing other engineering tasks.
Key Takeaways
-
AI Docs: A persistent knowledge base for AI coding tools.
-
Specs: A directory for detailed plans that drive AI-powered development.
-
.claude (or equivalent): A repository for reusable prompts, including context priming.
By implementing these three directories, you can significantly scale your engineering work, pass off more tasks to AI coding tools, and ultimately build software more efficiently. It is important to emphasize the patterns and principles that underpin this new age of engineering, and avoid being overly focused on any specific tool.