Scaffold Claude

scaffold-claude

Scaffold a CLAUDE.md for the user's project. Output is written to a scratchpad so the user can review and move it to the repo root themselves.

The file you produce documents edge cases, non-obvious choices, and tribal knowledge — things Claude can't read off package.json, the directory tree, or the README. If a fact is derivable, it does not belong in the file.

The Iron Rule

Never write a section based on inference. Always ask, and stub when the answer is "skip" or "I don't know."

A stubbed section (a <!-- TODO: ... --> comment) is strictly better than a section filled with plausible-sounding guesses. Guesses encode false confidence that future Claude will trust.

When to Use

• User says /scaffold-claude or asks to "scaffold/write/create CLAUDE.md"
• User asks for an AGENTS.md (same shape, different filename — ask which)
• User has a project but no CLAUDE.md and wants one
• User has a CLAUDE.md they want to redo from scratch

When NOT to Use

• User wants to edit an existing CLAUDE.md surgically → just edit it, don't run the full interview
• User wants a tiered, full-codebase AGENTS.md across many directories → use the intent-layer-capture skill instead
• User wants project-level CLAUDE.md updates triggered by code changes → that's a hook, not this skill

Output Location

Write to: docs/scratchpad/CLAUDE.md (relative to the user's current working directory)

• Confirm the path with the user before writing.
• If docs/scratchpad/ doesn't exist, create it.
• If a file already exists at that path, ask before overwriting.
• Do NOT write to the repo root. The user moves the file when they're satisfied.

The Workflow

1. Scan (read-only, narrow)

Read these if they exist, only to identify what to ask about — not to fill in:

• package.json, Gemfile, pyproject.toml, go.mod, Cargo.toml (any one that's present)
• Top-level directory listing (just names, not contents)
• README.md (skim, do not summarize into the CLAUDE.md)
• Existing CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md — if any exist, mention them and ask whether to merge or start fresh

State what you found in one or two sentences. Example: "Saw a Next.js + Drizzle setup with a lib/ directory and no existing CLAUDE.md. I won't assume anything about your conventions — I'll ask."

2. Interview

Walk through the 8 sections one at a time, in order, using the scripts in references/interview-questions.md:

1. Header paragraph
2. Stack
3. Commands
4. Architecture (only what isn't obvious)
5. Conventions
6. Hard constraints
7. Pointers to deeper docs
8. Gotchas (tribal knowledge)

For each section:

• Ask the question(s) from the reference.
• Always offer "skip" as a valid answer.
• If the user gives content, echo your paraphrase back before recording it.
• If the user says "skip" or "I don't know" or "nothing interesting there," stub the section — do not pad it.

Do not batch all questions into one big message. The user's attention is the bottleneck; one section per turn.

3. Write

Use templates/claude-md-stub.md as the base. Fill in confirmed content. Leave every skipped section as the original <!-- TODO: ... --> stub from the template — do not delete the stubs, they help future-you know what was deliberately left blank.

Write to docs/scratchpad/CLAUDE.md after confirming the path.

4. Close

Tell the user:

• The path you wrote
• Which sections are filled vs stubbed
• "Move it to the repo root when you're happy with it. Claude Code auto-loads CLAUDE.md at the root of any project."

No marketing flourishes. No "Now your project is well-documented!" Just the facts.