The 'agents.md' file is an open format that functions like a README, but specifically for AI agents. It provides a dedicated, predictable place to store context and instructions, ensuring the AI consistently follows rules for commits, tests, and project setup across all your repositories.
Related Insights
The all-caps `clod` file, created via the `init` command, stores project structure and user-defined rules. Unlike temporary in-chat instructions that get lost or degraded as the conversation continues, this file is referenced in every session, ensuring consistent behavior and enforcing project-wide guardrails.
To improve an agent's performance on a specific task like prompting the VO3 video model, create a dedicated 'onboarding document'. Use a tool like Perplexity to gather best practices from experts, compile them into a doc, and instruct the agent to reference it. This shortcuts the learning curve and embeds expertise.
Instead of using siloed note-taking apps, structure all your knowledge—code, writing, proposals, notes—into a single GitHub monorepo. This creates a unified, context-rich environment that any AI coding assistant can access. This approach avoids vendor lock-in and provides the AI with a comprehensive "second brain" to work from.
Instead of codebases becoming harder to manage over time, use an AI agent to create a "compounding engineering" system. Codify learnings from each feature build—successful plans, bug fixes, tests—back into the agent's prompts and tools, making future development faster and easier.
Instead of a complex database, store content for personal AI tools as simple Markdown files within the code repository. This makes information, like research notes, easily renderable in a web UI and directly accessible by AI agents for queries, simplifying development and data management for N-of-1 applications.
To maximize an AI agent's effectiveness, establish foundational software engineering practices like typed languages, linters, and tests. These tools provide the necessary context and feedback loops for the AI to identify, understand, and correct its own mistakes, making it more resilient.
To get consistent, high-quality results from AI coding assistants, define reusable instructions in dedicated files (e.g., `prd.md`) within your repository. This "agent briefing" file can be referenced in prompts, ensuring all generated assets adhere to a predefined structure and style.
When building multi-agent systems, tailor the output format to the recipient. While Markdown is best for human readability, agents communicating with each other should use JSON. LLMs can parse structured JSON data more reliably and efficiently, reducing errors in complex, automated workflows.
Documentation is shifting from a passive reference for humans to an active, queryable context for AI agents. Well-structured docs on internal APIs and class hierarchies become crucial for agent performance, reducing inefficient and slow context window stuffing for faster code generation.
Run separate instances of your AI assistant from different project directories. Each directory contains a configuration file providing specific context, rules, and style guides for that domain (e.g., writing vs. task management), creating specialized, expert assistants.
