Agent Files

RAPID generates and manages instruction files that AI agents use to understand your project.

Overview

Different AI tools read context from different files:

Agent	Instruction File	Format
Claude Code	CLAUDE.md	Markdown
OpenCode	AGENTS.md	Markdown
Aider	.aider.conf.yml	YAML
Generic	AGENTS.md	Markdown

Generation

RAPID generates instruction files when you run:

rapid init
# or
rapid start

Configuration

Control generation in rapid.json:

{
  "context": {
    "files": ["README.md", "CONTRIBUTING.md"],
    "dirs": ["docs/"],
    "generateAgentFiles": true
  }
}

Generated vs Manual

Setting	Behavior
generateAgentFiles: true	Generate templates, preserve user edits
generateAgentFiles: false	User creates and maintains files

---

CLAUDE.md

Instruction file for Claude Code.

Template

# Project: {{project-name}}

## Overview

{{Generated from README.md}}

## Code Style

- Language: {{detected-language}}
- Framework: {{detected-framework}}

## Commands

```
npm run dev    # Start development
npm test       # Run tests
npm run build  # Build project
```

## Project Structure

```
{{generated-tree}}
```

## Guidelines

- Follow existing code patterns
- Write tests for new features
- Use descriptive commit messages

## Restrictions

- Do not modify package-lock.json directly
- Do not commit .env files
- Ask before deleting files

Customization

Edit CLAUDE.md to add project-specific instructions:

# Project: my-api

## Overview

REST API for user management built with Express and TypeScript.

## Code Style

- Use async/await, never callbacks
- Prefer named exports
- Add JSDoc comments to public functions
- Use Zod for validation

## Database

- PostgreSQL via Prisma ORM
- Run migrations: `npx prisma migrate dev`
- Generate client: `npx prisma generate`

## Testing

- Jest for unit tests
- Supertest for API tests
- Maintain >80% coverage

## API Patterns

All endpoints follow this pattern:

```typescript
router.get('/resource', async (req, res, next) => {
  try {
    const result = await service.getResource();
    res.json(result);
  } catch (error) {
    next(error);
  }
});
```

## Important Files

- `src/index.ts` - Entry point
- `src/config.ts` - Configuration
- `src/middleware/auth.ts` - Authentication
- `prisma/schema.prisma` - Database schema

---

AGENTS.md

Generic instruction file used by OpenCode and others.

Template

# Agent Instructions

## Project

{{project-name}} - {{description}}

## Tech Stack

- {{languages}}
- {{frameworks}}
- {{tools}}

## Key Files

{{important-files}}

## Commands

{{detected-scripts}}

## Guidelines

{{from-contributing-md}}

Customization

# Agent Instructions

## Project

my-app - Full-stack web application

## Tech Stack

- Frontend: React, TypeScript, Tailwind
- Backend: Node.js, Express, Prisma
- Database: PostgreSQL
- Testing: Jest, Playwright

## Key Files

- `apps/web/` - React frontend
- `apps/api/` - Express backend
- `packages/shared/` - Shared types
- `docker-compose.yml` - Local services

## Commands

- `pnpm dev` - Start all services
- `pnpm test` - Run all tests
- `pnpm build` - Build all packages
- `pnpm db:migrate` - Run migrations

## Architecture

Monorepo using pnpm workspaces.

Frontend communicates with backend via REST API.
Backend uses repository pattern for data access.

## Guidelines

- Keep components small and focused
- Use custom hooks for shared logic
- Write integration tests for API endpoints
- Use transactions for multi-step operations

## Do Not

- Modify CI/CD files without review
- Add dependencies without discussion
- Change database schema without migration

---

.aider.conf.yml

Configuration file for Aider.

Template

# Generated by RAPID

# Model configuration
model: gpt-4o

# Git integration
auto-commits: true
gitignore: true

# Context
map-tokens: 1024

# UI
dark-mode: true

Customization

# Model - use Claude for better reasoning
model: claude-3-5-sonnet-20241022

# Or use GPT-4 for speed
# model: gpt-4o

# Git
auto-commits: true
gitignore: true
attribute-commits: true
attribute-author: 'Aider <aider@example.com>'

# Context window
map-tokens: 2048

# Files to always include
read:
  - README.md
  - CONTRIBUTING.md
  - docs/architecture.md

# Files to never edit
ignore:
  - '*.lock'
  - 'dist/**'
  - 'node_modules/**'

# UI preferences
dark-mode: true
pretty: true
stream: true

---

Per-Agent Files

Create agent-specific instruction files:

OPENCODE.md

# OpenCode Instructions

## Model Preference

Use Claude for complex tasks, GPT-4 for quick edits.

## Session Settings

- Always ask before making changes
- Show diffs before applying

## Project-Specific

...

CURSOR.md

# Cursor Instructions

## Composer Settings

- Use TypeScript strict mode
- Prefer functional components

## Project-Specific

...

---

File Updates

Automatic Updates

RAPID updates generated sections while preserving your edits:

# Project: my-app

<!-- RAPID:AUTO-START -->

## Commands

- npm run dev
- npm test
<!-- RAPID:AUTO-END -->

## My Custom Section

This is preserved during updates.

Manual Updates

Disable auto-updates for a file:

{
  "context": {
    "generateAgentFiles": true,
    "preserve": ["CLAUDE.md"]
  }
}

---

Context Sources

RAPID uses these sources to generate instruction files:

Source	Used For
README.md	Project overview
CONTRIBUTING.md	Guidelines, code style
package.json	Commands, dependencies
.gitignore	Files to ignore
Directory structure	Project layout

Custom Context

Add custom files to context:

{
  "context": {
    "files": ["README.md", "docs/architecture.md", "docs/api-reference.md"],
    "dirs": ["docs/", "specs/"]
  }
}

---

Best Practices

Content Guidelines

1. Be specific - Generic instructions are ignored
2. Include examples - Show code patterns
3. List restrictions - What NOT to do
4. Update regularly - Keep in sync with code

Size Guidelines

File	Recommended Size
CLAUDE.md	500-2000 words
AGENTS.md	300-1000 words
.aider.conf.yml	Minimal config only

Version Control

• Commit instruction files to git
• Review changes in PRs
• Update when architecture changes

---

Troubleshooting

Agent ignoring instructions

1. Verify file location (project root)
2. Check file name matches agent config
3. Ensure file is not in .gitignore
4. Try more explicit instructions

Instructions too long

AI models have context limits. If your file is too long:

1. Remove redundant information
2. Focus on project-specific details
3. Link to docs instead of including them

Conflicting instructions

When using multiple agents:

1. Keep common instructions in AGENTS.md
2. Put agent-specific instructions in dedicated files
3. Avoid contradicting instructions across files