ai-development-scaffold/.claude/README.md

# 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/
│   ├── 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/
│   ├── 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
```

## 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"
}
```