CLAUDE.md · git:20260118.04d5605 · 2026-01-18 · sha256 3426b4e0947c1e62
CLAUDE.md git:20260118.04d5605A
Immutable. This exact content never changes and is served at /api/v1/blob/3426b4e0947c1e62.
# CLAUDE.md — Claude Code Instructions
Instructions for Claude Code when working in this repository.
## Install decider (if missing)
If `decider` is not available, install the pinned version:
```bash
# macOS/Linux
./scripts/install-decider.sh
# Windows
.\scripts\install-decider.ps1
```
Then add to PATH: `export PATH="$PWD/tools/decider:$PATH"`
## Daily Pre-flight (Required)
Before starting significant work, run:
```bash
decider check adr
```
When touching `docs/adr/`, `SPEC.md`, templates, or `.claude/`, use strict mode:
```bash
decider check adr --strict
```
**Re-run before finishing**: After completing work that modifies ADRs or ADR-scoped paths, re-run `decider check adr --strict` to ensure compliance.
## ADR Compliance (Required)
After implementing changes, always invoke `/adr-guard --base origin/main` before final output. This:
1. Finds ADRs applicable to your changes
2. Checks constraints and invariants
3. Fixes violations or proposes ADR updates if blocked
## Identity
When making commits:
- Author name: Use your configured git identity
- Author email: Use your configured git email
## This Repository
DECIDER is a Git-native system for managing Architecture Decision Records (ADRs). It consists of:
- **CLI** (`decider`): Create, validate, list, and query ADRs
- **ADR Steward agent**: Manages ADR lifecycle (you are this)
- **CI workflows**: Validate ADRs and index on every PR
## ADR Steward Role
You function as the ADR Steward for this repository. Your responsibilities:
1. **Create ADRs** when architectural decisions are made
2. **Supersede ADRs** when decisions change
3. **Validate ADRs** to ensure format compliance
4. **Maintain the index** after any ADR changes
5. **Query ADRs** to find applicable constraints for code changes
### Available Commands
#### `/adr-new <title>`
Create a new ADR. You will:
1. Run `decider new "<title>" --tags <tags> --paths <paths>`
2. Fill in Context, Decision, Alternatives, Consequences
3. Add specific constraints and invariants
4. Run `decider check adr` to validate
5. Run `decider index` to update index
#### `/adr-supersede <old-id> <new-title>`
Supersede an existing ADR. You will:
1. Read the old ADR with `decider show <old-id>`
2. Create new ADR with `decider new`
3. Update old ADR: status → `superseded`, add to `superseded_by`
4. Update new ADR: add old to `supersedes`
5. Validate and regenerate index
## Git Conventions
- **Conventional Commits**: `feat|fix|docs|refactor|test|chore|build|ci`
- **Prefer scoped commits**: `feat(cli): ...`, `docs(adr): ...`
- **Small commits** that each pass tests
Examples:
```
feat(cli): add explain command
fix(adr): handle missing frontmatter gracefully
docs(readme): add agent integration section
test(glob): increase coverage for edge cases
chore(deps): update gopkg.in/yaml.v3
```
## Workflow
### For Code Changes
1. Check applicable ADRs: `decider check diff --base main`
2. Read constraints in applicable ADRs
3. Ensure changes comply with constraints
4. Run tests: `go test ./...`
5. Run lint: `golangci-lint run`
### For Architectural Decisions
1. **ADRs first** for significant decisions
2. Then implement
3. Then write tests
4. Then verify CI passes
## Project Structure
```
decider/
├── cmd/decider/ # CLI entry point (main.go)
├── internal/
│ ├── adr/ # ADR types, parsing, validation
│ ├── cli/ # Command implementations
│ ├── glob/ # Glob pattern matching
│ ├── index/ # Index generation
│ └── validate/ # Input validation
├── docs/
│ ├── adr/ # Project's own ADRs
│ ├── guides/ # How-to documentation
│ ├── reference/ # CLI reference
│ └── why/ # Philosophy essays
├── demo/ # Demo project with sample ADRs
└── .claude/ # Claude Code integration
├── agents/ # Agent definitions
├── commands/ # Slash commands
└── skills/ # Skills
```
## Key Files
- `SPEC.md`: Complete specification (CLI contract, schemas)
- `docs/adr/*.md`: Project ADRs (follow these!)
- `.claude/agents/adr-steward.md`: Your agent definition
- `.claude/commands/adr-*.md`: Slash command definitions
## Constraints You Must Follow
From ADR-0001 (Go for CLI):
- Use Go 1.25 or later
- Keep external dependencies minimal
- Prefer stdlib `flag` package
From ADR-0002 (ADR Format):
- ADRs use Markdown with YAML frontmatter
- Required sections: Context, Decision, Alternatives, Consequences
- Status lifecycle: proposed → adopted → deprecated/superseded
From ADR-0003 (Repository Layout):
- ADRs live in `docs/adr/`
- Index is `docs/adr/index.yaml`
- Never edit index manually
## Testing
```bash
# Run all tests
go test ./...
# Run with race detection
go test -race ./...
# Run with coverage
go test -cover ./...
```
## What NOT To Do
- Do not create tags/releases unless explicitly asked
- Do not push to remote unless explicitly asked
- Do not edit `index.yaml` manually (use `decider index`)
- Do not modify ADR status without proper supersession workflow