Claude Code Deep Dive: Architecture, Governance, and Engineering Practices - Tw93

This handbook distills six months of hands-on Claude Code usage across two accounts. It covers context management, Skills, Hooks, Subagents, prompt caching, and CLAUDE.md design, with a focus on making agent collaboration stable, governed, and verifiable.

Tw93Tw93

Project Contract

Build And Test

• Install: pnpm install
• Dev: pnpm dev
• Test: pnpm test
• Typecheck: pnpm typecheck
• Lint: pnpm lint

Architecture Boundaries

• HTTP handlers live in src/http/handlers/
• Domain logic lives in src/domain/
• Do not put persistence logic in handlers
• Shared types live in src/contracts/

Coding Conventions

• Prefer pure functions in domain layer
• Do not introduce new global state without explicit justification
• Reuse existing error types from src/errors/

Safety Rails

NEVER

• Modify .env, lockfiles, or CI secrets without explicit approval
• Remove feature flags without searching all call sites
• Commit without running tests

ALWAYS

• Show diff before committing
• Update CHANGELOG for user-facing changes

Verification

• Backend changes: make test + make lint
• API changes: update contract tests under tests/contracts/
• UI changes: capture before/after screenshots

Compact Instructions

Preserve:

1. Architecture decisions (NEVER summarize)
2. Modified files and key changes
3. Current verification status (pass/fail commands)
4. Open risks, TODOs, rollback notes