ai-development-scaffold/.claude

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):

   mv ~/.claude ~/.claude.backup
   

2. Deploy this configuration:

   cp -r .claude/* ~/.claude/
   chmod +x ~/.claude/hooks/*.sh
   

3. Verify installation:

   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/
│   ├── tdd-guardian.md          # TDD enforcement
│   ├── code-reviewer.md         # PR review (uses Opus)
│   ├── security-scanner.md      # Security checks
│   ├── refactor-scan.md         # Refactoring assessment (TDD step 3)
│   └── dependency-audit.md      # Vulnerability/outdated package checks
├── skills/
│   ├── 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)

# 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

# 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)

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

Customization

Project-Specific CLAUDE.md

Add a CLAUDE.md in your project root to override or extend settings:

# 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:

{
  "hooks": {
    // "PreToolUse": [...]
  }
}

Coverage Requirements

Layer	Target
Domain/Business Logic	90%+
API Routes	80%+
Infrastructure/DB	70%+
UI Components	80%+

Quick Reference

Commands by Language

# 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):

   git init
   

2. Copy the .gitignore (from this scaffold repo):

   cp /path/to/ai-development-scaffold/.gitignore .
   

3. Set up git hooks:

   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):

   touch CLAUDE.md
   # Add project-specific rules
   

Troubleshooting

Hooks not running

# 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:

{
  "model": "opusplan"
}