Skip to content

Commit 94c4fd1

Browse files
Namanv0509Namanv0509
authored
Merge branch 'master' into kanvas
2 parents 2238c0a + 89cbc42 commit 94c4fd1

3 files changed

Lines changed: 413 additions & 188 deletions

File tree

‎src/collections/blog/2025/10-09-2025-agents-instructions/post.mdx‎

Lines changed: 119 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -17,38 +17,41 @@ published: true
1717

1818
import { BlogWrapper } from "../../Blog.style.js";
1919
import { Link } from "gatsby";
20+
import ReadmeAgents from "./readme-agents.webp";
2021

2122
<BlogWrapper>
2223

2324
AI coding assistants are everywhere. They live in our terminals, they're built into our IDEs, and they've fundamentally changed how we write software. From Codex and Copilot to Gemini and Claude, developers now have a powerful new collaborator.
2425

25-
But there's a problem. To be effective, these AI agents need context. They need to understand your project's architecture, coding standards, and specific rules. This guidance lives in configuration files, but every agent speaks a different language.
26+
But, there's a problem. To be effective, these AI agents need context. They need to understand your project's architecture, coding standards, and specific rules. This guidance lives in configuration files, but every agent speaks a different language.
2627

27-
You might have a CLAUDE.md for Claude, a .cursor/rules/ directory for Cursor, and a .github/copilot-instructions.md for Copilot. This fragmentation creates a digital Tower of Babel in your repository. When you switch tools or collaborate with a team using different agents, you're stuck translating the same core instructions into multiple formats.
28+
You might have a `CLAUDE.md` for Claude, a `.cursor/rules/` directory for Cursor, and `.github/copilot-instructions.md` for Copilot, and a `JULES.md` for Google Jules. This fragmentation creates a digital Tower of Babel in your repository. When you switch tools or collaborate with a team using different agents, you're stuck translating the same core instructions into multiple formats.
2829

2930
What if there was a universal translator? A single, standardized file to provide context to *any* AI coding agent?
3031

3132
That’s the idea behind **AGENTS.md**: an open standard for guiding AI coding agents.
3233

33-
### **What We'll Cover**
34+
### What We'll Cover
3435

3536
* **What is AGENTS.md?** The "README for AI."
3637
* **Why Do We Need It?** Taming the chaos of configuration files.
3738
* **What Goes Inside?** A practical guide to crafting your own AGENTS.md.
3839
* **Making It Work Today:** Bridging AGENTS.md with your current tools.
3940
* **The Future is Unified:** What's next for AI-native development.
4041

41-
### **1\. What is AGENTS.md?**
42+
### What is AGENTS.md?
4243

4344
Think of it this way: README.md is the front door for human developers. It's the first place you look to understand a project's purpose, setup, and contribution guidelines.
4445

46+
<img src={ReadmeAgents} width="50%"></img>
47+
4548
**AGENTS.md is the front door for AI agents.** It’s a single, standardized markdown file in the root of your project where AI assistants can get all the context they need to become a high-performing teammate.
4649

4750
This simple idea is already gaining traction. With support from tools like Codex, Cursor, and Gemini CLI, AGENTS.md has been adopted by over 40,000 open-source projects.
4851

49-
### **2\. Why AGENTS.md? The Case for a Universal Standard**
52+
### Why AGENTS.md? The Case for a Universal Standard
5053

51-
Developers are already feeling the pain of config fragmentation. On GitHub, users of tools like [Claude Code](https://www.google.com/search?q=https://github.com/example/claude-code/issues/123) and [Cline](https://www.google.com/search?q=https://github.com/example/cline/issues/456) have opened issues asking for a unified standard, specifically pointing to AGENTS.md.
54+
Developers are already feeling the pain of config fragmentation. On GitHub, users of tools like Claude Code and Cline have opened issues asking for a unified standard, specifically pointing to AGENTS.md.
5255

5356
Here’s the problem without a standard:
5457

@@ -58,90 +61,151 @@ Here’s the problem without a standard:
5861

5962
AGENTS.md solves this by creating a single source of truth.
6063

61-
Instead of a tangled mess of agent-specific files, you have one clean, universal file that works across all tools.
64+
Instead of a tangled mess of agent-specific files, you have one clean, universal file that works across all tools, which can come with its own drawbacks.
6265

63-
### **3\. What Goes Inside an AGENTS.md File?**
66+
### Why you might want to use multiple AI code assistant configuration files
6467

65-
AGENTS.md consolidates the essential knowledge required to contribute to your project effectively. It's a living document that captures your team's conventions, architectural decisions, and operational knowledge.
68+
Using multiple configuration files for an AI code assistant can offer a few benefits, most noteably is that of allowing for specialization, consistency, and tighter control in more complex projects.
6669

67-
Here’s a practical example of what a robust AGENTS.md might look like:
70+
#### Improved project-specific customization
71+
72+
- Tailored behavior: A configuration file can be set up for a specific project or microservice to guide the AI with project-specific settings. This ensures the AI understands the unique context, coding style, and framework of that codebase, providing more accurate and relevant suggestions.
73+
- Contextual awareness: For large codebases, AI assistants perform better when the code is organized into modular files. This allows the AI to process each file's context more effectively without being overloaded, leading to faster and more accurate suggestions.
74+
- Optimized performance: You can create lightweight configurations for smaller tasks or projects that don't require the AI to have a deep understanding of the entire codebase. This can reduce processing time and resource consumption.
75+
76+
#### Enhanced flexibility and control
6877

69-
\# AGENTS.md: Project Constitution for AI Assistants
78+
- Switching models: By having multiple configurations, you can easily switch between different AI models, like Claude, GitHub Copilot, or a self-hosted model, to determine which is best for a specific task. This prevents vendor lock-in and allows you to always use the most effective tool.
79+
- Experimentation: Developers can experiment with different prompts, settings, and AI models by creating separate, isolated configuration files. This allows for testing and fine-tuning without disrupting the main project workflow.
7080

71-
\#\# 1\. Project Overview & Core Purpose
72-
\- \*\*Purpose:\*\* This is a customer support ticketing system built with a React frontend and a Node.js (Express) backend.
73-
\- \*\*Tech Stack:\*\* TypeScript, React, Tailwind CSS, Node.js, Express, PostgreSQL.
74-
\- \*\*Key Goal:\*\* Provide a fast, reliable, and user-friendly interface for support agents to manage customer issues.
81+
#### Streamlined team collaboration
7582

76-
\#\# 2\. Architecture & Design Patterns
77-
\- \*\*Database:\*\* We use PostgreSQL for its reliability and ACID compliance. All business logic involving payments or user accounts must be transactional.
78-
\- \*\*Caching:\*\* Redis is used for session storage and caching non-critical data. Never cache user-private data.
79-
\- \*\*State Management (Frontend):\*\* Use React Query for server state and Zustand for global UI state. Avoid prop-drilling.
80-
\- \*\*API Design:\*\* We follow RESTful principles. All API error responses must include a \`requestId\` for easier debugging.
83+
- Consistent guidance: A team can share a standard configuration file to ensure all members receive the same AI guidance. This helps enforce consistent coding practices, security rules, and tool usage across the entire development workflow.
84+
- Centralized management: Centralizing API keys and other secrets within managed configurations allows for secure collaboration. Teams can roll out pre-approved AI models and workflows while retaining oversight of their data.
85+
- Reduced inconsistency: A standard configuration file prevents inconsistent AI outputs that can arise when different team members use different settings or prompts, which is a major headache for Python projects and others
8186

82-
\#\# 3\. Code Standards & Conventions
83-
\- \*\*Formatting:\*\* We use Prettier with the settings in \`.prettierrc\`. All code must be formatted on commit.
84-
\- \*\*Linting:\*\* ESLint is configured with rules in \`.eslintrc.js\`. Pay close attention to rules against using \`any\`.
85-
\- \*\*Naming:\*\*
86-
\- Components: \`PascalCase\` (e.g., \`TicketList.tsx\`)
87-
\- API endpoints: \`kebab-case\` (e.g., \`/api/user-tickets\`)
88-
\- Functions: \`camelCase\` (e.g., \`fetchUserData\`)
89-
\- \*\*Testing:\*\* Use Jest and React Testing Library. All new components must have at least 80% test coverage for critical paths.
87+
### What's the difference between AI code assistant configuration files?
9088

91-
\#\# 4\. Build, Test, & Deploy Pipeline
92-
\- \*\*Local Setup:\*\* Run \`npm install\` and then \`npm run dev\`.
93-
\- \*\*Running Tests:\*\* \`npm test\`
94-
\- \*\*Build Command:\*\* \`npm run build\`
95-
\- \*\*Deployment:\*\* Pushes to the \`main\` branch trigger a GitHub Actions workflow that deploys to Vercel.
89+
To improve the AI's relevance and prevent security issues, developers can explicitly control which parts of a codebase the AI should focus on or ignore.
90+
- `.aiignore`: Similar to a `.gitignore` file, this file tells the AI which files and folders to exclude from its analysis. This is critical for security, as it prevents the AI from being exposed to sensitive information.
91+
- `.github/copilot-instructions.md`: This file contains custom instructions specifically for GitHub Copilot, guiding its behavior and code generation according to project standards or user preferences.
92+
- `AGENTS.md`: These files are associated with the concept of "agents" in AI coding, particularly with tools like GitHub Copilot's coding agent. They can define behaviors and instructions for these agents, potentially at a more granular level than the general copilot-instructions.md. AGENTS.md suggests a collection of agent definitions.
93+
- `CLAUDE.md`: This file serves a similar purpose to copilot-instructions.md but is specifically designed for the Claude AI model, allowing users to provide custom instructions for its interactions and code generation.
94+
- `.cursorrules`, `.windsurfrules`, `.clinerules`: These files, and their directory counterparts, contain configuration or rule sets for specific AI coding tools.
9695

97-
\#\# 5\. Common Pitfalls & API Nuances
98-
\- \*\*Stripe API:\*\* All POST requests are idempotent. It's safe to retry them.
99-
\- \*\*SendGrid API:\*\* This API has strict rate limits. All email-sending tasks should be pushed to our Redis queue.
100-
\- \*\*Authentication:\*\* If you see auth errors locally, it's likely because the Redis server died. Restart it with \`redis-server\`.
10196

102-
\#\# 6\. Git & PR Workflow
103-
\- \*\*Branch Naming:\*\* \`feature/ticket-123-add-search-bar\`
104-
\- \*\*Commit Messages:\*\* Follow the Conventional Commits specification. (e.g., \`feat: add user profile page\`)
105-
\- \*\*Pull Requests:\*\* Must be reviewed by at least one other team member before merging. Link the associated ticket in the PR description.
97+
README.md: This is a standard Markdown file used in most software projects to provide an overview, instructions, and other essential information about the project. While not directly tied to AI assistant configuration, it can implicitly guide AI tools by providing context about the codebase.
10698

107-
**Start small, and let it grow.** Your AGENTS.md doesn't need to be perfect on day one. Begin with the most critical information and expand it over time. Each time a developer (or an agent) learns something new about the project, add it to the file.
99+
The key distinction is between files designed to configure and instruct specific AI coding assistants (e.g., Copilot, Claude, Cursor, Windsurf) and general project documentation (README.md) that provides human-readable information about the project. The AI configuration files differ based on the particular AI tool they target and the specific instructions or rules they convey to that tool.
108100

109-
### **4\. Bridging AGENTS.md with Existing Tools**
101+
102+
### What Goes Inside an AGENTS.md File?
103+
104+
AGENTS.md consolidates the essential knowledge required to contribute to your project effectively. It's a living document that captures your team's conventions, architectural decisions, and operational knowledge.
105+
106+
Here’s a practical example of what a robust AGENTS.md might look like:
107+
108+
```markdown
109+
# AGENTS.md: Project Constitution for AI Assistants
110+
111+
## 1. Project Overview & Core Purpose
112+
- **Purpose:** This is a customer support ticketing system built with a React frontend and a Node.js (Express) backend.
113+
- **Tech Stack:** TypeScript, React, Tailwind CSS, Node.js, Express, PostgreSQL.
114+
- **Key Goal:** Provide a fast, reliable, and user-friendly interface for support agents to manage customer issues.
115+
116+
## 2. Architecture & Design Patterns
117+
- **Database:** We use PostgreSQL for its reliability and ACID compliance. All business logic involving payments or user accounts must be transactional.
118+
- **Caching:** Redis is used for session storage and caching non-critical data. Never cache user-private data.
119+
- **State Management (Frontend):** Use React Query for server state and Zustand for global UI state. Avoid prop-drilling.
120+
- **API Design:** We follow RESTful principles. All API error responses must include a \`requestId\` for easier debugging.
121+
122+
## 3. Code Standards & Conventions
123+
- **Formatting:** We use Prettier with the settings in \`.prettierrc\`. All code must be formatted on commit.
124+
- **Linting:** ESLint is configured with rules in \`.eslintrc.js\`. Pay close attention to rules against using \`any\`.
125+
- **Naming:**
126+
- Components: \`PascalCase\` (e.g., \`TicketList.tsx\`)
127+
- API endpoints: \`kebab-case\` (e.g., \`/api/user-tickets\`)
128+
- Functions: \`camelCase\` (e.g., \`fetchUserData\`)
129+
- **Testing:** Use Jest and React Testing Library. All new components must have at least 80% test coverage for critical paths.
130+
131+
## 4. Build, Test, & Deploy Pipeline
132+
- **Local Setup:** Run \`npm install\` and then \`npm run dev\`.
133+
- **Running Tests:** \`npm test\`
134+
- **Build Command:** \`npm run build\`
135+
- **Deployment:** Pushes to the \`main\` branch trigger a GitHub Actions workflow that deploys to Vercel.
136+
137+
## 5. Common Pitfalls & API Nuances
138+
- **Stripe API:** All POST requests are idempotent. It's safe to retry them.
139+
- **SendGrid API:** This API has strict rate limits. All email-sending tasks should be pushed to our Redis queue.
140+
- **Authentication:** If you see auth errors locally, it's likely because the Redis server died. Restart it with \`redis-server\`.
141+
142+
## 6. Git & PR Workflow
143+
- **Branch Naming:** \`feature/ticket-123-add-search-bar\`
144+
- **Commit Messages:** Follow the Conventional Commits specification. (e.g., \`feat: add user profile page\`)
145+
- **Pull Requests:** Must be reviewed by at least one other team member before merging. Link the associated ticket in the PR description.
146+
```
147+
148+
*Start small, and let it grow.* Your AGENTS.md doesn't need to be perfect on day one. Begin with the most critical information and expand it over time. Each time a developer (or an agent) learns something new about the project, add it to the file.
149+
150+
### Bridging AGENTS.md with Existing Tools
110151

111152
While many modern agents support AGENTS.md out of the box, some older tools still look for their own native config files. For those, you can use two simple bridging strategies to get them to read your central AGENTS.md file.
112153

113-
#### **Method 1: Symbolic Linking (Recommended)**
154+
#### Method 1: Symbolic Linking
114155

115156
A symbolic link (symlink) is a pointer to another file. You can create symlinks that trick agents into reading AGENTS.md while looking for their native file.
116157

117158
Open your terminal in the project root and run these commands for the tools you use:
118159

119-
\# For Claude Code
120-
ln \-s AGENTS.md CLAUDE.md
160+
<pre><code class="language-shell">
161+
# For Claude Code
162+
ln -s AGENTS.md CLAUDE.md
121163

122-
\# For Cursor
123-
mkdir \-p .cursor/rules
124-
ln \-s ../../AGENTS.md .cursor/rules/rules.mdc
164+
# For Cursor
165+
mkdir -p .cursor/rules
166+
ln -s ../../AGENTS.md .cursor/rules/rules.mdc
125167

126-
\# For GitHub Copilot
127-
mkdir \-p .github
128-
ln \-s ../AGENTS.md .github/copilot-instructions.md
168+
# For GitHub Copilot
169+
mkdir -p .github
170+
ln -s ../AGENTS.md .github/copilot-instructions.md
171+
</code></pre>
129172

130173
Your tools continue to work as expected, but now they all draw their context from a single source.
131174

132-
#### **Method 2: Using Imports**
175+
#### Method 2: Using Imports
133176

134177
Some agents support importing one markdown file into another. For example, in Claude Code's CLAUDE.md file, you can simply add a line to import your universal file:
135178

179+
<pre><code>
136180
\# In ./CLAUDE.md
137181

138182
@AGENTS.md
139183

140-
\# You can add Claude-specific instructions below if needed
184+
# You can add Claude-specific instructions below if needed
185+
</code></pre>
141186

142187
This approach keeps your setup clean and ensures AGENTS.md remains the primary source of truth.
143188

144-
### **What's Next: The Future of AI Collaboration**
189+
#### What's the difference between agents.md and prompt.md?
190+
191+
`AGENTS.md` and `.prompt.md` files serve different purposes in guiding an AI coding assistant. AGENTS.md provides general, project-level context, while .prompt.md files define reusable, task-specific instructions. A `.prompt.md` file defines a reusable, task-specific prompt that can be executed directly by an AI assistant.
192+
Purpose: Automate common, repeatable development tasks. A `.prompt.md`:
193+
194+
- Encapsulates complex tasks: Lets you define and reuse complex, multi-step instructions for specific jobs.
195+
- Task specialization: Creates a specialized prompt for common tasks, such as generating a test case or scaffolding a component.
196+
- Chat integration: Some AI assistants, like GitHub Copilot in VS Code, allow developers to run prompt files directly from the chat interface using a slash command.
197+
198+
**Key differences summarized**
199+
200+
|| Aspect || AGENTS.md || .prompt.md ||
201+
| Scope | Project-wide | Task-specific |
202+
| Purpose | Defines general rules and project context for any task | Automates specific, repeatable tasks |
203+
| Trigger | Automatically referenced by the AI for every interaction | Manually invoked by the user, often via a chat command |
204+
| Content | High-level instructions, conventions, and setup details | Detailed instructions and examples for a single, focused task |
205+
| Analogy | A handbook for the AI | A macro or recipe for the AI |
206+
207+
208+
### What's Next: The Future of AI Collaboration
145209

146210
AGENTS.md is more than just a configuration file; it's a step toward a future where AI and human developers collaborate seamlessly.
147211

0 commit comments

Comments
 (0)