# AGENTS.md Templates

## Key Principles

- Concise: dense, human-readable content; one line per concept when possible.
- Actionable: commands should be copy-paste ready.
- Project-specific: document patterns unique to this repo.
- Current: reflect the actual codebase and active tooling.
- Scoped: put broad rules at the repo root; put narrow rules in nested `AGENTS.md` or `AGENTS.override.md`.

## Recommended Sections

Use only sections that matter for the project.

### Commands

```markdown
## Commands

| Command | Purpose |
| --- | --- |
| `<install command>` | Install dependencies |
| `<dev command>` | Start development server |
| `<build command>` | Production build |
| `<test command>` | Run tests |
| `<lint command>` | Lint or format |
```

### Architecture

```markdown
## Architecture

```
<root>/
  <dir>/    # <purpose>
  <dir>/    # <purpose>
  <dir>/    # <purpose>
```
```

### Key Files

```markdown
## Key Files

- `<path>` - <purpose>
- `<path>` - <purpose>
```

### Code Style

```markdown
## Code Style

- <project-specific convention>
- <preference over alternative>
```

### Environment

```markdown
## Environment

Required:
- `<VAR_NAME>` - <purpose>

Setup:
- <setup step>
```

### Testing

```markdown
## Testing

- `<test command>` - <what it tests>
- <testing convention or pattern>
```

### Gotchas

```markdown
## Gotchas

- <non-obvious issue, prerequisite, or ordering dependency>
```

### Workflow

```markdown
## Workflow

- <when to do X>
- <preferred approach for Y>
```

## Minimal Project Root Template

```markdown
# <Project Name>

<One-line description>

## Commands

| Command | Purpose |
| --- | --- |
| `<command>` | <description> |

## Architecture

```
<structure>
```

## Gotchas

- <gotcha>
```

## Comprehensive Project Root Template

```markdown
# <Project Name>

<One-line description>

## Commands

| Command | Purpose |
| --- | --- |
| `<command>` | <description> |

## Architecture

```
<structure with descriptions>
```

## Key Files

- `<path>` - <purpose>

## Code Style

- <convention>

## Environment

- `<VAR>` - <purpose>

## Testing

- `<command>` - <scope>

## Gotchas

- <gotcha>
```

## Nested Override Template

Use this for a subdirectory whose rules differ from the repo root.

```markdown
# <Directory> Instructions

## Scope

- Applies to `<path>/`.

## Local Rules

- <specific rule that differs from root guidance>

## Verification

- `<command>` - <focused check for this directory>
```