Agent Configuration Files

Agent configuration files are the single highest leverage point in the agentic tools harness. They load into every conversation, making them both powerful and dangerous — powerful because they shape every interaction, dangerous because bloated or irrelevant content degrades all interactions.

Each tool uses its own filename — see Tool Configuration Reference for yours. The principles below apply to all of them.

The Golden Rule

For every line in your agent configuration file, ask: “Would removing this cause the AI agent to make mistakes?”

If the answer is no — delete it. AI coding agents are in-context learners. They follow existing code patterns without explicit instructions. Only document what the agent can’t infer.

What to Include

1. Commands the Agent Can’t Guess

## Commands
- Test single: `pnpm vitest run src/path/to/test`
- Test all: `pnpm test`
- Typecheck: `pnpm tsc --noEmit`
- Lint + fix: `pnpm biome check --write`
- Dev server: `pnpm dev` (port 3000)
- DB migrate: `pnpm drizzle-kit push`

2. Conventions That Differ from Defaults

## Conventions
- Use Result<T, E> pattern, never throw exceptions
- All dates stored as UTC, displayed in user's timezone
- API responses wrapped in { data, error, meta } envelope
- Feature flags checked via `flags.isEnabled('feature-name')`

3. Architecture the Agent Can’t Infer

## Architecture
- src/api/ — REST endpoints (one file per resource)
- src/services/ — Business logic (no direct DB access)
- src/repos/ — Database layer (Drizzle ORM)
- src/workers/ — Background jobs (BullMQ)
- Requests flow: API → Service → Repo → DB

4. Non-Obvious Project Gotchas

## Gotchas
- Auth tokens are in Redis, not the DB — check src/lib/redis.ts
- The test DB resets between files but NOT between tests in a file
- Never import from src/internal/ — these are auto-generated

What to Exclude

Category	Why Exclude	Alternative
Style guides	Use a linter — faster, cheaper, deterministic	Biome/ESLint + hooks
Standard conventions	The AI agent already knows them	Trust in-context learning
API documentation	Changes frequently, bloats context	Link to docs instead
File-by-file descriptions	The agent reads files when needed	Let it discover
Tutorials or long explanations	Wastes tokens every session	Use skills instead
Code snippets	Become outdated quickly	Use file:line pointers

Never Send an LLM to Do a Linter's Job

LLMs are expensive and slow compared to traditional linters. Style guidelines add irrelevant instructions into your context window, degrading performance on actual tasks. Use Biome or ESLint with hooks for formatting — reserve your agent configuration file for instructions only humans can evaluate.

Optimal Length

Research shows a clear correlation between agent configuration file length and instruction adherence:

Lines	Rule Application Rate	Recommendation
< 60	~95%	Ideal
60-200	~92%	Good
200-400	~85%	Prune if possible
400+	~71%	Too long — split into skills

Target: under 60 lines. HumanLayer’s own root CLAUDE.md is under 60 lines and manages a complex project effectively.

The WHY-WHAT-HOW Framework

Structure your agent configuration file around three questions:

WHAT (Tech Stack)

## Stack
- TypeScript 5.4, Node.js 22
- Framework: Hono (NOT Express)
- ORM: Drizzle
- Testing: Vitest + Playwright
- Package manager: pnpm (NOT npm)

WHY (Architecture Rationale)

## Architecture
- Services never access DB directly (testability)
- All external API calls go through src/clients/ (mockable)
- Request flow: Route → Middleware → Handler → Service → Repo

HOW (Workflows)

## Workflow
- Always run typecheck after code changes
- Run single test files, not the full suite (performance)
- Commit with conventional commits (feat:, fix:, refactor:)

Advanced Patterns

Import References

Some agent configuration files support a @path/to/file syntax to reference other files. For example, Claude Code’s CLAUDE.md supports this natively:

# Project Overview
See @README.md for project description and @package.json for available commands.

## Additional Context
- Git workflow: @docs/git-workflow.md
- API conventions: @docs/api-conventions.md

This keeps the root file concise while providing access to detailed documentation when needed. Check your specific tool’s documentation for equivalent include or reference syntax.

Emphasis for Critical Rules

Use emphasis markers for rules that must never be violated:

## IMPORTANT
- NEVER commit to main directly — always use feature branches
- ALWAYS run `pnpm test` before committing
- YOU MUST use the Result pattern for error handling

Research shows that emphasis markers (“IMPORTANT”, “YOU MUST”, “NEVER”) improve instruction adherence for critical rules across AI coding agents.

Progressive Disclosure via Skills

Move domain-specific knowledge to skills or supplementary files:

# Root agent config file — loaded every session
## Commands
[universal commands]

## Conventions
[universal conventions]

# Skill file (loaded on demand)
# .agents/skills/api-development/skill.md
## API Conventions
[detailed API patterns, auth flow, validation rules]

The pattern — load universal rules always, load domain knowledge on demand — is the same across all tools. See Tool Configuration Reference for where your tool stores skill files.

Maintenance

Treat your agent configuration file like code:

• Review it when your AI agent misbehaves — the file might be too long or ambiguous
• Prune regularly — remove rules the agent follows naturally
• Test changes — observe whether the agent’s behavior actually shifts after edits
• Version control it — check it into git so your team can contribute

Tip

If the AI agent keeps doing something wrong despite having a rule against it, the file is probably too long and the rule is getting lost. Shorten the file.

Complete Example

The structure below applies regardless of your tool’s filename — see Tool Configuration Reference for the exact filename to use.

# MyApp

## Stack
TypeScript 5.4, Hono, Drizzle ORM, Vitest, pnpm

## Commands
- Dev: `pnpm dev`
- Test: `pnpm vitest run <path>`
- Test all: `pnpm test`
- Types: `pnpm tsc --noEmit`
- Lint: `pnpm biome check --write`
- DB push: `pnpm drizzle-kit push`

## Architecture
- src/routes/ — Hono route handlers
- src/services/ — Business logic (never imports from routes or repos directly)
- src/repos/ — Drizzle queries, one per table
- src/middleware/ — Auth, rate limiting, logging
- src/lib/ — Shared utilities

## Conventions
- Error handling: Result<T, E> pattern, never throw
- Validation: Zod schemas for all external input
- Dates: UTC storage, user-timezone display
- IDs: ULIDs via src/lib/id.ts

## IMPORTANT
- Run typecheck after every code change
- Write tests for all new API endpoints
- Never modify migration files after they're committed

38 lines. Everything the AI agent needs, nothing it doesn’t.