claude-md

What this skill does

# CLAUDE.md Skill

Write or review CLAUDE.md files that contain **only tacit knowledge** — information an AI agent cannot derive by reading the codebase, running tools, or inspecting configuration files.

## Core Principle

> If a linter, compiler, `ls`, or `grep` can tell the agent the same thing, it does not belong in CLAUDE.md.

CLAUDE.md transfers understanding that lives in engineers' heads: architectural invariants, non-obvious constraints, known violations awaiting cleanup, and workflow gotchas that require tribal knowledge.

## Supported Actions

- **Create**: Write a new CLAUDE.md for a directory
- **Review**: Evaluate an existing CLAUDE.md against the quality bar
- **Improve**: Refactor an existing CLAUDE.md to remove derivable content and strengthen tacit knowledge

## Step 1 — Determine Action and Scope

Parse the user's request:

- If they specify a directory path, scope to that directory.
- If no path, default to the project root.
- Determine action: **create**, **review**, or **improve**.

CLAUDE.md files can be placed in any directory to cover that subtree. A subdirectory CLAUDE.md supplements (does not replace) parent CLAUDE.md files.

## Step 2 — Gather Context

Before writing or reviewing, understand the codebase:

1. **Read existing CLAUDE.md files** in the target directory and its parents.
2. **Inspect the directory** — run `ls`, read key config files (`Makefile`, `package.json`, `go.mod`, `BUILD`, `.eslintrc`, `tsconfig.json`, etc.).
3. **Identify what tooling already covers** — linter rules, formatter configs, CI pipelines, type systems.
4. **Mine PR review comments** — extract tacit knowledge from code review history (see Step 2a).
5. **Talk to the user** — ask what non-obvious constraints, gotchas, or architectural decisions exist that the code doesn't express.

### Step 2a — Mine PR Review Comments

PR code reviews are one of the richest sources of tacit knowledge. Reviewers often explain *why* something is wrong in ways that never make it into documentation. Mine this knowledge with `gh`:

```bash
# Recent merged PRs touching the target directory
gh pr list --state merged --limit 30 --json number,title,url

# Review comments on a specific PR
gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {path, body, diff_hunk}'

# Review-level comments (general PR feedback, not inline)
gh api repos/{owner}/{repo}/pulls/{number}/reviews --jq '.[] | select(.state != "APPROVED") | {body, state}'
```

**What to look for in review comments:**

| Signal | Example | Extracts To |
|---|---|---|
| **"Don't do X because..."** | "Don't import `pkg/internal` from here — it breaks the dependency boundary" | Architectural boundary |
| **"This broke prod when..."** | "Last time someone changed this serialization, the mobile app crashed for 2 hours" | Operational gotcha |
| **"The convention is..."** | "We always put migration SQL in `migrations/` not inline — the deploy pipeline expects it there" | Workflow procedure |
| **"This needs to match..."** | "This enum must stay in sync with the proto definition in repo X" | Cross-team constraint |
| **Repeated corrections** | Same feedback given across multiple PRs | Undocumented rule worth capturing |
| **"Why" explanations** | "We use X instead of Y because Y has a memory leak under Z conditions" | Non-obvious design rationale |

**Process:**

1. Fetch the last 20–30 merged PRs touching the target directory.
2. For each PR, read inline review comments and review-level feedback.
3. Filter for comments that explain *constraints*, *boundaries*, *gotchas*, or *rationale* — skip style nits and typo fixes.
4. Group recurring themes — if the same feedback appears in 2+ PRs, it is almost certainly undocumented tacit knowledge.
5. Apply the quality bar (Step 3) to each extracted item before including it.

**Limitations:** Only mine reviews if the repo is hosted on GitHub and `gh` is authenticated. Skip this step if `gh auth status` fails or the repo has no PR history.

## Step 3 — Apply the Quality Bar

Every piece of content must pass this checklist:

| Check | Question |
|---|---|
| **Tacit knowledge** | Would an agent reading source code and tool configs miss this? |
| **Non-derivable or hard-to-derive** | Can `ls`, `grep`, linter output, or config files reproduce this? If yes, would an agent reliably get it right on the first try? |
| **Architectural invariant** | Does it describe a rule not enforced by tooling? |
| **Known violations** | If documenting a rule, are existing violations called out? |
| **Actionable** | Does it give concrete steps, not vague guidance? |
| **Not code explanation** | Does it avoid restating what functions do? |
| **Concise** | Uses tables, short bullets, or headings — not prose walls? |

### Hard-to-Derive Exception

Some information is technically derivable but practically hard to get right. Apply this test:

> Even if an agent *could* find this by searching, would it reliably find the *correct* answer on the first try?

If the answer is **probably not** — because the information is buried, ambiguous, or commonly confused — it belongs in CLAUDE.md despite being technically derivable.

| Category | Example |
|---|---|
| **Niche tool flags** | A CLI flag that looks like it does one thing but behaves differently in this project's context |
| **Subtle config interactions** | Two settings that are individually documented but whose combination produces unexpected behavior |
| **Error-prone defaults** | A tool where the obvious usage is wrong and the correct invocation requires project-specific knowledge |
| **Version-pinned behavior** | A tool invocation where the default behavior changed between versions and the project pins an older version |

This exception does **not** apply to content that is straightforward to derive — directory listings, standard lint rules, or well-documented API usage remain excluded.

### The Natural Language Execution Test

> If you gave this CLAUDE.md to a competent engineer who has never seen the codebase, would they avoid a mistake they would otherwise make?

If **yes**, keep it. If **no** — because tooling or code review would catch it — remove it.

## Step 4 — Write or Revise Content

### Content That Belongs

| Category | Example |
|---|---|
| **Architectural boundaries** | "Vendor formats must be parsed only inside `topomap/` — all other packages use `topomap.Graph`" |
| **Non-obvious design rationale** | "Shortest paths are precomputed with Dijkstra because the graph is static and small" |
| **Operational gotchas** | "Run `ms_local_ctl down` when done — Cloud SQL Proxy impersonation accounts are limited" |
| **Workflow procedures** | Step-by-step for tasks the code can't express (e.g., "how to add a new vendor format") |
| **Cross-team constraints** | "Service X owns the schema — changes require their review even though we have write access" |
| **Non-obvious environment setup** | "Must run `gcloud auth` with impersonation flag before local dev works" |
| **Migration context** | "Package `oldauth` is deprecated — new code must use `auth/v2`. Known users: [list]" |
| **PR review wisdom** | Recurring reviewer feedback that reveals undocumented rules, boundaries, or gotchas |
| **Hard-to-derive tool usage** | "Must pass `--legacy-peer-deps` to `npm install` — the default resolver fails on our pinned React 17 peer deps" |
| **Subtle config interactions** | "Setting `GOMAXPROCS=1` in CI is intentional — the race detector produces false positives with higher values on this codebase" |

### Content to Reject

| Anti-Pattern | Why It Fails | Alternative |
|---|---|---|
| Lint rules | Derivable from linter config | Let the linter do its job |
| Directory listings (names only) | Derivable from `ls` | OK if adding constraints or relationships |
| Code explanations | Derivable from reading code | Document *why*, not *what* |
| Language style guides | Derivable from formatter config | Only project-specific deviations |
| Dependency lists | Derivab