CTO / VP Engineering

# CLAUDE.md — CTO / VP Engineering
> Version: 2026-02-17 | Difficulty: advanced

## What Your AI Can Now Do
- Generate monthly engineering reports with DORA metrics, uptime, and business impact framing
- Draft architecture decision records from a conversation about trade-offs
- Run blameless incident postmortems with structured timelines and action items
- Surface tech debt inventory with velocity impact before quarterly planning
- Prepare board-ready slides that translate engineering work into business outcomes

---

## Quick Start
1. Add your infrastructure and deployment tool credentials in `.env`
2. Document your first architecture decision using `/architecture-review`
3. Run `/eng-report` to see how Claude pulls delivery and reliability data together
4. Set up your team structure in `org/teams/` so Claude knows ownership boundaries
5. Log current tech debt in `strategy/tech-debt/` with severity and velocity impact

---

## About Me
CTO or VP Engineering leading 20-80 engineers across 4-8 teams.
Split between technical strategy, people leadership, and business communication.
Biggest challenges: hiring senior talent, balancing debt vs. velocity, and 99.95% reliability.

---

## Pre-Built Commands

| Command | What It Does |
|---------|-------------|
| `/architecture-review` | Evaluate a proposed change for scaling risk, reliability, and migration complexity |
| `/eng-report` | Generate monthly report — velocity, reliability, hiring, and initiative status |
| `/incident-review` | Structure a blameless postmortem with timeline, root cause, and action items |
| `/board-prep` | Draft board slides framing engineering metrics as business outcomes |
| `/tech-debt-audit` | Inventory current debt with velocity drag and recommended paydown order |

---

## How Claude Connects to Your Tools

| Tool | Why You Need It |
|------|----------------|
| Supabase | Production database queries, system health, deployment data |
| Google Workspace | Engineering reports, ADRs, board decks, hiring pipeline docs |
| GitHub | PR velocity, deployment frequency, release tracking |
| Memory | Architecture decisions, tech debt history, org context across quarters |

### Setup
```bash
# Required in .env
SUPABASE_URL=your-project-url
SUPABASE_KEY=your-service-key
GITHUB_TOKEN=your-token
```

---

## Engineering Leadership Rules
- **MUST:** Document every significant architecture decision as an ADR with context, 3+ options including "do nothing", and rationale
- **MUST:** Frame all engineering metrics with business context — "47 PRs shipped" means nothing to the board
- **MUST:** Complete incident review within 48 hours of any P1 — blameless but rigorous
- **SHOULD:** Default to buy over build unless it's a core differentiator or lock-in is catastrophic
- **MUST:** Track tech debt as a budget item — quantify velocity impact and pay it down deliberately
- **SHOULD:** Classify decisions as one-way or two-way doors — two-way doors get decided fast
- **MUST:** Never lower the hiring bar to fill a seat — wrong senior hire costs 6+ months
- **SHOULD:** Measure what matters: deployment frequency, lead time, change failure rate, MTTR

---

## Project Structure
```
strategy/
  roadmap/
  decisions/
  tech-debt/
org/
  teams/
  hiring/
  development/
operations/
  incidents/
  metrics/
  runbooks/
board/
  reports/
  metrics/
```

### What These Folders Mean
- `strategy/` — Quarterly roadmap, ADRs (numbered, never deleted, only superseded), and tech debt inventory
- `org/` — Team charters, ownership maps, hiring rubrics, and leadership development plans
- `operations/` — Incident postmortems, monthly DORA metrics, and operational runbooks
- `board/` — Quarterly board decks and key metrics with trends and commentary

---

## Automation

| When | What Happens | If It Fails |
|------|-------------|-------------|
| P1 incident resolved | Auto-creates postmortem template with timeline and owner | Create blank postmortem and flag for manual review |
| Month end | Pulls DORA metrics, deployments, and uptime into report draft | Prompt to manually export metrics from dashboards |
| ADR created | Auto-numbers, dates, and adds to decision log index | Manually assign next number from the index |
| Quarterly planning | Surfaces tech debt with velocity impact for prioritization | Review tech-debt folder and flag items over 3 months old |
| Board meeting in 5 days | Drafts slide deck with latest metrics and narrative | Send reminder to prepare deck with metric sources |

---

## Gotchas
- **MUST:** Never present engineering metrics without business context — translate to revenue, customer, or velocity impact
- **MUST:** Rewriting from scratch is almost never the answer — strangler fig beats big bang
- **SHOULD:** Design teams around desired system boundaries — Conway's Law is not optional
- **MUST:** Start board prep 3x earlier than feels necessary — last-minute decks show
- **SHOULD:** If you're the bottleneck on decisions, build decision-making capacity in your team

---

## Memory & Learning
Claude builds context over time:
- Architecture decisions and their measured outcomes over quarters
- Tech debt inventory with paydown progress and velocity recovery
- Team health signals, attrition patterns, and hiring pipeline status
- Incident patterns and systemic reliability improvements
- Board feedback on which communication approaches landed

To save something important: just say "remember that [fact]" in conversation.
To review saved memories: use the `/memory` command to open the memory editor.