Optimal Repository Layout

Repository structure is the first thing an AI coding agent encounters. A well-organized repo gives agents a “map” of the codebase — reducing exploration time, minimizing context consumption, and improving code generation accuracy.

The Agentic-Optimized Structure

project-root/
├── <agent-config-file>        # Root: universal instructions (under 60 lines)
├── .agents/                   # Agentic infrastructure
│   ├── settings.json          # Permissions, hooks configuration
│   ├── skills/                # On-demand domain knowledge
│   │   ├── research/skill.md
│   │   ├── implement/skill.md
│   │   └── deploy/skill.md
│   ├── agents/                # Custom sub-agents
│   │   ├── reviewer.md
│   │   ├── security-auditor.md
│   │   └── test-writer.md
│   └── commands/              # Reusable slash commands
│       ├── research-codebase.md
│       ├── create-plan.md
│       └── implement-plan.md
├── .sdlc/                     # Spec-driven development artifacts
│   ├── specs/                 # Feature specifications
│   ├── plans/                 # Implementation plans
│   └── research/              # Research summaries
├── src/
│   ├── <agent-config-file>    # Source-specific conventions
│   ├── api/
│   │   └── <agent-config-file> # API-specific patterns
│   ├── services/
│   ├── repos/
│   └── types/
├── tests/
│   └── <agent-config-file>    # Testing conventions
├── docs/                      # Documentation
└── package.json

Note

The exact directory name (.agents/) and agent config filename vary by tool — see Tool Configuration Reference for your tool’s convention.

Why This Structure Works

Hierarchical Agent Configuration Files

AI coding agents automatically load their configuration file from the root and from directories they work in. This creates a natural progressive disclosure:

Level	File	Contents	Token Cost
Root	Agent config file	Universal: tech stack, commands, architecture overview	~500 tokens
Source	src/ config file	Source conventions: patterns, naming, imports	~300 tokens
Domain	src/api/ config file	Domain-specific: API patterns, auth, error handling	~200 tokens

Only the relevant levels load for each task. An agent working in src/api/ gets all three; one working in docs/ gets only the root.

The Agentic Infrastructure Directory

This directory (your tool’s configuration directory) holds your agentic infrastructure:

• skills/ — Domain knowledge files loaded on-demand (not every session)
• agents/ — Custom sub-agents with their own tool permissions and model preferences
• commands/ — Reusable prompts invoked via slash command or equivalent

Tip

Skills differ from agent configuration files in a critical way: they load on demand, not every session. Use your root configuration file for universal rules and skills for domain-specific knowledge.

The .sdlc/ Directory

Borrowed from spec-driven development, this directory stores workflow artifacts:

• specs/ — Feature specifications in markdown (the “source code” of intent)
• plans/ — Step-by-step implementation plans (survive compaction)
• research/ — Codebase research summaries (reusable across sessions)

These files persist across sessions and compaction events, providing continuity for long-running features.

Monorepo Considerations

For monorepos, the hierarchical agent configuration pattern scales naturally:

monorepo/
├── <agent-config-file>          # Universal: monorepo structure, shared commands
├── packages/
│   ├── api/
│   │   ├── <agent-config-file>  # API-specific conventions
│   │   └── src/
│   ├── web/
│   │   ├── <agent-config-file>  # Frontend conventions
│   │   └── src/
│   └── shared/
│       ├── <agent-config-file>  # Shared package rules
│       └── src/
└── .agents/                     # Agentic infrastructure (use your tool's path)
    ├── skills/
    │   ├── api-development/skill.md
    │   └── frontend-development/skill.md
    └── agents/
        ├── api-agent.md         # Specialized for API work
        └── frontend-agent.md    # Specialized for React work

Caution

The monorepo root agent configuration file should be especially concise — it loads for EVERY task across ALL packages. Keep it to structural overview and shared commands only.

Anti-Patterns

Over-Documented Roots

# BAD: 400-line agent configuration file
- [File-by-file descriptions of every module]
- [Detailed API documentation]
- [Complete style guide]
- [Long tutorials]

Rule application drops from 92% to 71% beyond 400 lines. If the AI agent already does something correctly, don’t document it.

Flat Structure

# BAD: Everything at root level
project/
├── CLAUDE.md (everything in one file)
├── auth.ts
├── database.ts
├── api.ts
└── ... (200 more files)

Agents waste context exploring flat structures. Group by domain, and put domain-specific guidance in domain-level configuration files.

Missing Commands

If agents need to run commands that aren’t obvious, they’ll guess wrong. Always document:

## Commands
- Test single: `pnpm vitest run src/path/to/test.ts`
- Test all: `pnpm test`
- Build: `pnpm build`
- Typecheck: `pnpm tsc --noEmit`

Key Takeaways

• Use hierarchical agent configuration files: root (universal) → source (conventions) → domain (specific)
• Keep the root configuration file under 60 lines — every line must prevent a concrete mistake
• Store agentic infrastructure in your tool’s configuration directory — skills, agents, commands
• Store workflow artifacts in .sdlc/ (specs, plans, research)
• Use progressive disclosure: load domain knowledge on demand, not universally
• In monorepos, keep the root configuration file especially minimal