james.bland
3f0786f1e7
`.claude/agents/` was the source of truth, which made every role Claude-Code shaped. Adding a second client meant rewriting each role in that client's syntax and maintaining both copies — the drift this scaffold exists to prevent, one layer up. Roles and skills now live under `.agents/` and render into each registered client. `.claude/agents/`, `.claude/skills/` and `.codex/agents/` are generated; `scripts/sync-agent-integrations.py --check` fails on drift and belongs in CI. The role metadata is portable rather than vendor-named: `reasoning_tier` (deep/balanced/fast/vision), `capabilities`, `mutation`, `invocation`, and an optional `preload_skills`. A client manifest maps those to native syntax and must declare what it cannot express — `codex.yaml` declares `tier_policy: unsupported` and its adapters say so in the file, rather than the tier silently evaporating and leaving the repository to believe it was enforced. The port is behaviour-preserving where it should be and a fix where it should not. Every instruction body is byte-identical — the whole diff to `.claude/agents/` is 18 added lines and zero deletions. What changed is frontmatter that was missing: - four agents (`code-reviewer`, `tdd-guardian`, `dependency-audit`, `pr-creator`) declared no `tools:` and therefore inherited the ENTIRE tool pool, so three review-only agents could edit and write the code they were reviewing. All eight now declare capabilities explicitly. - the six read-only roles gain a non-editing permission mode, so the constraint is enforced by the client rather than by the prompt asking nicely. - `mutation` is now explicit, which records the two roles that genuinely need to write: `pr-creator` (external-write — it pushes a branch and opens a PR) and `dependency-audit` (workspace-write — package managers rewrite lockfiles). `pr-creator` keeps `shell` because opening a PR needs it, but it is now the only agent here with a write mutation and a declared reason for it, instead of one of four with unlimited access by omission.
323 lines
8.7 KiB
Markdown
323 lines
8.7 KiB
Markdown
# Claude Code Configuration
|
|
|
|
A comprehensive guidance system for Claude Code with strict TDD enforcement, multi-language support, and infrastructure patterns.
|
|
|
|
## Quick Start
|
|
|
|
1. **Backup existing config** (if any):
|
|
```bash
|
|
mv ~/.claude ~/.claude.backup
|
|
```
|
|
|
|
2. **Deploy this configuration**:
|
|
```bash
|
|
cp -r .claude/* ~/.claude/
|
|
chmod +x ~/.claude/hooks/*.sh
|
|
```
|
|
|
|
3. **Verify installation**:
|
|
```bash
|
|
ls ~/.claude/
|
|
# Should show: CLAUDE.md, settings.json, agents/, skills/, hooks/
|
|
```
|
|
|
|
## Structure
|
|
|
|
```
|
|
~/.claude/
|
|
├── CLAUDE.md # Core principles (~150 lines)
|
|
├── settings.json # Model config (opusplan), Claude hooks
|
|
├── agents/ # GENERATED from ../.agents/roles — do not edit
|
|
│ ├── tdd-guardian.md # TDD enforcement (sonnet)
|
|
│ ├── code-reviewer.md # PR review (opus)
|
|
│ ├── security-scanner.md # Security checks (sonnet, read-only)
|
|
│ ├── refactor-scan.md # Refactoring assessment (sonnet, read-only)
|
|
│ ├── dependency-audit.md # Vulnerability/outdated package checks (sonnet)
|
|
│ ├── pr-creator.md # Automated PR creation (haiku)
|
|
│ ├── release-notes.md # CHANGELOG generation (haiku, read-only)
|
|
│ └── plan-reviewer.md # Plan validation (sonnet, read-only)
|
|
├── skills/ # GENERATED from ../.agents/skills — do not edit
|
|
│ ├── languages/
|
|
│ │ ├── python/SKILL.md # pytest, Ruff, FastAPI
|
|
│ │ ├── typescript/SKILL.md # Vitest, ESLint, React
|
|
│ │ ├── rust/SKILL.md # cargo test, clippy
|
|
│ │ ├── go/SKILL.md # go test, golangci-lint
|
|
│ │ ├── java/SKILL.md # JUnit 5, Spring Boot
|
|
│ │ └── csharp/SKILL.md # xUnit, .NET Clean Architecture
|
|
│ ├── testing/
|
|
│ │ ├── tdd/SKILL.md # TDD workflow
|
|
│ │ ├── ui-testing/SKILL.md # React Testing Library
|
|
│ │ └── browser-testing/SKILL.md # Playwright, Chrome MCP
|
|
│ ├── infrastructure/
|
|
│ │ ├── aws/SKILL.md # AWS patterns
|
|
│ │ ├── azure/SKILL.md # Azure patterns
|
|
│ │ ├── gcp/SKILL.md # GCP patterns
|
|
│ │ ├── terraform/SKILL.md # Terraform IaC
|
|
│ │ ├── ansible/SKILL.md # Ansible automation
|
|
│ │ ├── docker-kubernetes/SKILL.md # Containers & orchestration
|
|
│ │ ├── database/SKILL.md # DB patterns, Alembic migrations
|
|
│ │ └── cicd/SKILL.md # Jenkins, GitHub Actions, GitLab CI
|
|
│ └── patterns/
|
|
│ ├── monorepo/SKILL.md # Workspace patterns
|
|
│ ├── api-design/SKILL.md # REST API patterns
|
|
│ └── observability/SKILL.md # Logging, metrics, tracing
|
|
└── hooks/
|
|
├── check-secrets.sh # Claude hook: Block secrets in code
|
|
├── auto-format.sh # Claude hook: Auto-format on save
|
|
├── pre-commit-tdd.sh # Git hook script: TDD enforcement
|
|
└── example-git-hooks/
|
|
└── pre-commit # Example git hook (copy to .git/hooks/)
|
|
```
|
|
|
|
## Model Strategy
|
|
|
|
Uses `opusplan` mode:
|
|
- **Opus** for planning, architecture, code review
|
|
- **Sonnet** for code execution, testing, implementation
|
|
|
|
## Key Features
|
|
|
|
### TDD Enforcement
|
|
- Strict RED-GREEN-REFACTOR cycle
|
|
- 80%+ coverage requirement
|
|
- Tests must be written before code
|
|
|
|
### Type Safety
|
|
- Python: Pydantic v2, mypy strict
|
|
- TypeScript: Strict mode, Zod schemas
|
|
- Rust: Full type system utilization
|
|
|
|
### Security
|
|
- Automatic secret detection
|
|
- Blocks commits with credentials
|
|
- Security scanner agent
|
|
|
|
### Multi-Language Support
|
|
- Python (FastAPI, pytest, Ruff)
|
|
- TypeScript (React, Vitest, ESLint)
|
|
- Rust (Tokio, cargo test, clippy)
|
|
- Go (go test, golangci-lint, Chi)
|
|
- Java (Spring Boot, JUnit 5, Mockito)
|
|
- C# (.NET, xUnit, Clean Architecture)
|
|
- Terraform (AWS/Azure/GCP modules)
|
|
- Ansible (playbooks, roles)
|
|
|
|
### Multi-Cloud Support
|
|
- AWS (Lambda, ECS, S3, Secrets Manager)
|
|
- Azure (App Service, Functions, Key Vault)
|
|
- GCP (Cloud Run, Functions, Secret Manager)
|
|
|
|
## Hooks Explained
|
|
|
|
This configuration includes **two types of hooks**:
|
|
|
|
### 1. Claude Hooks (Automatic)
|
|
Defined in `settings.json`, these run automatically during Claude sessions:
|
|
- **check-secrets.sh** - Blocks file writes containing secrets (PreToolUse)
|
|
- **auto-format.sh** - Auto-formats files after writes (PostToolUse)
|
|
|
|
These are configured via `settings.json` and require no additional setup.
|
|
|
|
### 2. Git Hooks (Manual Setup Required)
|
|
The `pre-commit-tdd.sh` script enforces TDD rules at git commit time. This is a **git hook**, not a Claude hook.
|
|
|
|
**Setup Option A: Symlink (recommended)**
|
|
```bash
|
|
# In your project directory
|
|
mkdir -p .git/hooks
|
|
ln -sf ~/.claude/hooks/example-git-hooks/pre-commit .git/hooks/pre-commit
|
|
chmod +x .git/hooks/pre-commit
|
|
```
|
|
|
|
**Setup Option B: Copy**
|
|
```bash
|
|
# In your project directory
|
|
mkdir -p .git/hooks
|
|
cp ~/.claude/hooks/example-git-hooks/pre-commit .git/hooks/pre-commit
|
|
chmod +x .git/hooks/pre-commit
|
|
```
|
|
|
|
**Setup Option C: Using Husky (Node.js projects)**
|
|
```bash
|
|
npm install -D husky
|
|
npx husky init
|
|
echo '~/.claude/hooks/pre-commit-tdd.sh' > .husky/pre-commit
|
|
```
|
|
|
|
**What the git hook does:**
|
|
- Verifies test files exist for changed production files
|
|
- Blocks commits that appear to violate TDD (code without tests)
|
|
- Can be bypassed with `git commit --no-verify` (use sparingly)
|
|
|
|
## Usage Examples
|
|
|
|
### Invoke TDD Guardian
|
|
```
|
|
@tdd-guardian Let's implement user authentication
|
|
```
|
|
|
|
### Code Review
|
|
```
|
|
@code-reviewer Review these changes before I merge
|
|
```
|
|
|
|
### Security Scan
|
|
```
|
|
@security-scanner Check this code for vulnerabilities
|
|
```
|
|
|
|
### Refactoring Assessment
|
|
```
|
|
@refactor-scan Assess this code for refactoring opportunities
|
|
```
|
|
|
|
### Dependency Audit
|
|
```
|
|
@dependency-audit Check for vulnerable or outdated packages
|
|
```
|
|
|
|
### Create Pull Request
|
|
```
|
|
@pr-creator Create a PR for this branch
|
|
```
|
|
|
|
### Generate Release Notes
|
|
```
|
|
@release-notes Generate changelog from v1.0.0 to HEAD
|
|
```
|
|
|
|
### Review Implementation Plan
|
|
```
|
|
@plan-reviewer Review docs/plans/active/3.5_business-capabilities.md
|
|
```
|
|
|
|
## Editing agents and skills
|
|
|
|
`.claude/agents/` and `.claude/skills/` are **generated**. The source of truth is
|
|
[`.agents/`](../.agents/README.md), which is client-neutral so the same roles and
|
|
skills also render for Codex (and any client added later) rather than being
|
|
rewritten per tool.
|
|
|
|
```bash
|
|
python3 scripts/sync-agent-integrations.py # regenerate
|
|
python3 scripts/sync-agent-integrations.py --check # fail on drift (use in CI)
|
|
```
|
|
|
|
Edit `.agents/roles/<name>.md` or `.agents/skills/**`, then run the sync. A direct
|
|
edit to a generated file is reverted by the next run.
|
|
|
|
## Customization
|
|
|
|
### Project-Specific CLAUDE.md
|
|
Add a `CLAUDE.md` in your project root to override or extend settings:
|
|
|
|
```markdown
|
|
# Project: My App
|
|
|
|
## Additional Rules
|
|
- Use PostgreSQL for all database work
|
|
- Deploy to AWS eu-west-2
|
|
```
|
|
|
|
### Disable Hooks
|
|
Comment out hooks in `settings.json`:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
// "PreToolUse": [...]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Coverage Requirements
|
|
|
|
| Layer | Target |
|
|
|-------|--------|
|
|
| Domain/Business Logic | 90%+ |
|
|
| API Routes | 80%+ |
|
|
| Infrastructure/DB | 70%+ |
|
|
| UI Components | 80%+ |
|
|
|
|
## Quick Reference
|
|
|
|
### Commands by Language
|
|
```bash
|
|
# Python
|
|
pytest --cov=src --cov-fail-under=80
|
|
ruff check . && ruff format .
|
|
|
|
# TypeScript
|
|
npm test -- --coverage
|
|
npm run lint && npm run typecheck
|
|
|
|
# Rust
|
|
cargo test && cargo clippy -- -D warnings
|
|
|
|
# Go
|
|
go test -cover ./...
|
|
golangci-lint run
|
|
|
|
# Java (Maven)
|
|
mvn test
|
|
mvn verify # Integration tests
|
|
|
|
# C# (.NET)
|
|
dotnet test --collect:"XPlat Code Coverage"
|
|
|
|
# Terraform
|
|
terraform validate && terraform fmt -check
|
|
```
|
|
|
|
## Starting a New Project
|
|
|
|
When starting a new project with this configuration:
|
|
|
|
1. **Initialize git** (if not already):
|
|
```bash
|
|
git init
|
|
```
|
|
|
|
2. **Copy the .gitignore** (from this scaffold repo):
|
|
```bash
|
|
cp /path/to/ai-development-scaffold/.gitignore .
|
|
```
|
|
|
|
3. **Set up git hooks**:
|
|
```bash
|
|
mkdir -p .git/hooks
|
|
ln -sf ~/.claude/hooks/example-git-hooks/pre-commit .git/hooks/pre-commit
|
|
chmod +x .git/hooks/pre-commit
|
|
```
|
|
|
|
4. **Add project-specific CLAUDE.md** (optional):
|
|
```bash
|
|
touch CLAUDE.md
|
|
# Add project-specific rules
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Hooks not running
|
|
```bash
|
|
# Ensure hooks are executable
|
|
chmod +x ~/.claude/hooks/*.sh
|
|
|
|
# Check hook syntax
|
|
bash -n ~/.claude/hooks/check-secrets.sh
|
|
```
|
|
|
|
### Skills not loading
|
|
Skills are auto-discovered from `~/.claude/skills/`. Ensure:
|
|
- Files are named `SKILL.md` (case-sensitive)
|
|
- YAML frontmatter is valid
|
|
- `description` field is present
|
|
|
|
### Model not switching
|
|
Verify `settings.json` has:
|
|
```json
|
|
{
|
|
"model": "opusplan"
|
|
}
|
|
```
|