Structuring AGENTS.md and CLAUDE.md Files

1. Understanding the AGENTS.md Standard

Aspect	Description	Usage
File Format	`AGENTS.md`	Standardized file for defining AI agents in development workflows
Structure	YAML or JSON format	Defines agent roles, capabilities, and interaction patterns
Purpose	Modular AI agent configuration	Enables reuse and orchestration of AI agents across projects

Example: AGENTS.md Structure

agents:
  - name: "CodeReviewer"
    role: "Automated Code Reviewer"
    capabilities:
      - "Static Analysis"
      - "Style Guide Enforcement"
    config:
      rules:
        - "No inline comments"
        - "Use of linters"

Note: The AGENTS.md format is designed to be human-readable and machine-parsable, supporting integration with CI/CD pipelines and AI agent orchestration tools.

2. Structuring CLAUDE.md Files

Section	Description	Best Practices
Overview	CLAUDE.md files provide structured documentation for AI agents, detailing their purpose, configuration, and usage.	Include a clear title and concise description of the agent's role.
Agent Configuration	Defines how the agent operates, including model selection, parameters, and behavior settings.	Use consistent formatting for configuration options to improve readability.
Usage Examples	Provides practical examples of how to interact with the agent in various scenarios.	Include real-world use cases and sample prompts to guide users effectively.
Integration Points	Details how the agent integrates with other tools or systems within the development workflow.	Highlight dependencies and required setup steps for seamless integration.

Example: Basic CLAUDE.md Structure

# Agent: Code Assistant

## Overview
This agent assists developers in writing and debugging code by providing suggestions, explanations, and best practices.

## Configuration
- Model: claude-3-haiku-latest
- Temperature: 0.7
- Max Tokens: 1000

## Usage Examples
### Example 1: Debugging a Function
User: "Fix the bug in this function."
Assistant: [Provides corrected code and explanation]

### Example 2: Code Review
User: "Review this function for best practices."
Assistant: [Provides feedback and suggestions]

## Integration Points
- Supported IDEs: VSCode, IntelliJ
- API Endpoints: /api/agent/code-assistant

Note: Ensure that all configuration parameters are documented clearly to allow easy customization and deployment.

Warning: Avoid including sensitive information or hardcoded credentials in CLAUDE.md files.

3. Documenting Build and Test Commands

Command Type	Description	Example	Notes
build	Builds the project for deployment or testing	`npx tsc --build`	Can include transpilation, bundling, or compilation steps
test	Runs project tests	`npx jest --coverage`	May include unit, integration, or end-to-end tests
lint	Checks code for style and potential errors	`npx eslint src/`	Often used in CI pipelines to enforce code quality
format	Formats code according to style guidelines	`npx prettier --write src/`	Can be run as a pre-commit hook or in CI

Example: Defining Build and Test Commands in Package.json

{
  "scripts": {
    "build": "tsc --build",
    "test": "jest --coverage",
    "lint": "eslint src/",
    "format": "prettier --write src/"
  }
}

Note: Ensure that all commands are executable in the project's environment and that they are documented clearly for team members or CI systems.

4. Documenting Project Architecture

Example: Project Structure Documentation

# Project Architecture Overview

## Core Components
- **Frontend**: React + TypeScript
- **Backend**: Node.js + Express
- **Database**: PostgreSQL 15
- **AI Integration**: Claude API v2

## Data Flow
```mermaid
graph LR
    A[Frontend] --> B[API Gateway]
    B --> C[AI Service]
    C --> D[Database]
```

## Key Modules
| Module | Purpose | Status |
|--------|---------|--------|
| auth | User authentication | Stable |
| ai-agent | Claude integration | Beta |
| data-model | Database schema | Stable |

Documentation Element	Description	Best Practice
Project Overview	High-level description of the project's purpose and scope	Include mission statement, key features, and target audience
Component Diagrams	Visual representation of system components and their relationships	Use Mermaid.js or PlantUML for maintainable diagrams
Data Flow	Visual flow of data through the system	Document input, processing, and output paths
Module Descriptions	Breakdown of each functional module	Include purpose, dependencies, and status indicators

Note: Use consistent naming conventions for all architecture documentation elements to maintain clarity across the project.

Architecture Documentation Approaches

Traditional: Text-based descriptions with static diagrams
Modern: Interactive diagrams with live data integration
AI-Assisted: Automated generation from codebase analysis

5. Documenting Code Conventions

Convention	Description	Example
File Naming	Use kebab-case for all files	`data-fetcher.js`
Component Structure	Organize components in `src/components/` with subdirectories per feature	`src/components/user-profile/card.js`
Variable Naming	Use camelCase for variables and functions	`const userProfile = ...`
Constants	Use UPPER_SNAKE_CASE for constants	`const MAX_RETRY_ATTEMPTS = 3;`
Documentation Style	Use JSDoc for all public APIs	`/** * Fetches user data from the API. * @param {string} userId - The ID of the user to fetch * @returns {Promise<Object>} User data object */`

Example: JSDoc Usage

/**
 * Calculates the total price including tax.
 * @param {number} basePrice - The base price of the item
 * @param {number} taxRate - The tax rate as a decimal (e.g., 0.08 for 8%)
 * @returns {number} The total price including tax
 */
function calculateTotalPrice(basePrice, taxRate) {
  return basePrice * (1 + taxRate);
}

Note: Consistent documentation improves maintainability and helps new developers understand the codebase quickly.

File Type	Reference Method	Description
.md	`![alt](path/to/image.png)`	Inline image reference in Markdown
.md	`[Link Text](path/to/file.md)`	Internal Markdown link to another doc
.md	`<img src="path/to/image.png" />`	HTML image tag for inline media
.json	`"docs": "./docs/related.md"`	JSON config referencing documentation
.yaml	`docs: ./docs/related.md`	YAML config referencing documentation

Example: Internal Link in Markdown

[View API Reference](./api-reference.md)

Example: Image in Documentation

![Architecture Diagram](./diagrams/architecture.png)

Note: Ensure all relative paths are correct when moving or renaming documentation files.

7. Placing Agent Files at Repository Root

When structuring AI-assisted development projects, placing agent configuration files at the repository root ensures consistent access and management across all team members and CI/CD pipelines.

File	Description	Usage
.agent/claude.json	Configuration for Claude AI agent	Used by Claude to understand project context and rules
.agent/llm-config.yaml	LLM model and parameter settings	Defines which models to use for different tasks
.agent/agents.json	Agent registry and metadata	Lists all available agents and their capabilities

Example: .agent/claude.json

{
  "name": "claude-dev-agent",
  "model": "claude-3-sonnet",
  "max_tokens": 4096,
  "temperature": 0.7,
  "system_prompt": "You are a senior software engineer specializing in full-stack development..."
}

Note: The root placement allows tools like llm-agent-cli to automatically discover and load agent configurations without needing to traverse subdirectories.

Warning: Avoid placing agent files inside nested directories or src/ folders, as this can cause configuration loading issues in automated workflows.

8. Using Nested Agent Files per Directory

Organizing AI agents within nested directories promotes modularity and maintainability. Each directory can contain its own agent configuration, making it easier to manage complex workflows or teams of agents.

Directory Structure	Description	Use Case
/agents/project-agent	Primary agent for project management tasks	Task orchestration, planning
/agents/project-agent/subagents/data-collector	Specialized agent for collecting data from sources	Data gathering, API integration
/agents/project-agent/subagents/reporter	Agent responsible for generating reports	Summarization, formatting

Example: Nested Agent Configuration

{
  "name": "data-collector",
  "description": "Collects data from external APIs",
  "config": {
    "source": "https://api.example.com/data",
    "auth": "bearer token"
  }
}

Note: Nested agent files should follow a consistent naming convention to ensure clarity and ease of navigation.

Best Practices for Nested Agent Files

Keep configuration files small and focused
Use descriptive names for agent directories
Document the purpose of each nested agent
Ensure dependencies between agents are clearly defined

9. Synchronizing Agent Files Across Tools

File Type	Tool	Synchronization Method	Notes
.agent.json	Agent Studio	Manual Export/Import	Exported from Agent Studio, imported into other tools manually.
.agent.json	CLAUDE.md	Manual Export/Import	Exported from CLAUDE.md, imported into Agent Studio manually.
.agent.yaml	Agent Studio	Manual Export/Import	Exported from Agent Studio, imported into other tools manually.
.agent.yaml	CLAUDE.md	Manual Export/Import	Exported from CLAUDE.md, imported into Agent Studio manually.

Example: Synchronizing .agent.json Files

{
  "name": "Code Assistant",
  "description": "Assists with code generation and debugging",
  "version": "1.0.0",
  "tools": [
    {
      "name": "Code Generator",
      "type": "function"
    }
  ]
}

Note: Ensure that all tool definitions and configurations are consistent across tools to avoid runtime errors.

Warning: Manual synchronization can lead to inconsistencies if not carefully managed.

10. Migrating Between Agent File Formats

Agent File Format Comparison

AGENTS.md: Uses YAML for configuration, structured in a hierarchical format with agent and tasks sections.
CLAUDE.md: Uses Markdown with structured YAML blocks for configuration, often including task descriptions in natural language.

Feature	AGENTS.md	CLAUDE.md
Configuration Format	`YAML`	`Markdown with YAML blocks`
Task Definition	Structured under `tasks` key with `name`, `description`, and `steps`	Described in natural language within Markdown, with YAML blocks for structured data
Agent Metadata	Defined under `agent` key with `name`, `role`, and `goals`	Defined in YAML block at the top of the file with `name`, `role`, and `goals`
Support for Nested Tasks	Yes, using `subtasks` or nested structures	Yes, through natural language descriptions and structured YAML blocks

Migration Steps from AGENTS.md to CLAUDE.md

Extract Agent Configuration: Copy the agent section from AGENTS.md to a YAML block in CLAUDE.md.
Convert Task Definitions: Transform each task in AGENTS.md into a natural language description in CLAUDE.md, with structured YAML blocks for steps and subtasks.
Update References: Ensure any references to tasks or agents in other files are updated to reflect the new format.

Example: AGENTS.md to CLAUDE.md Migration

# AGENTS.md
agent:
  name: "Code Assistant"
  role: "Developer"
  goals:
    - "Assist in writing clean, efficient code"
tasks:
  - name: "Write a function"
    description: "Create a function that sums two numbers"
    steps:
      - "Define the function signature"
      - "Implement the logic"
      - "Test the function"

# CLAUDE.md
---
name: "Code Assistant"
role: "Developer"
goals:
  - "Assist in writing clean, efficient code"
---

## Task: Write a function

Create a function that sums two numbers.

### Steps:
1. Define the function signature
2. Implement the logic
3. Test the function