ragnar-pwninskjold/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.

The One-Shot Example

references/postlane-example.md contains a complete, real-world CLAUDE.md.

Use it to calibrate:

• The tone (terse, opinionated, every assertion has a because)
• The shape of each section (what kinds of facts go where)
• The discipline (nothing derivable from the codebase appears in the file)

Do NOT use it to:

• Pre-fill the user's file with Postlane's choices
• Copy any specific tech, command, gotcha, or PR reference
• Suggest the user "should" have any specific section filled — they shouldn't if they have nothing real to put there

When showing the example to the user, frame it as: "This is what a fully-filled-in version looks like. Yours will be shorter — most projects don't have this much tribal knowledge to document yet, and that's correct."

Rationalizations to Resist

| Rationalization | Reality | |---|---| | "Their package.json clearly shows Next.js — I'll just write that." | If Next.js choice has no story, it doesn't belong in Stack. Ask first. | | "Most projects use Prettier, I'll add a convention for it." | Most projects ≠ this project. Ask. | | "They didn't answer for Hard Constraints, but every project has some — let me suggest a few." | An empty stub is correct. Invented constraints are worse than no constraints. | | "The Gotchas section feels empty, let me add some 'common Next.js gotchas.'" | Gotchas are bug-fix archaeology specific to this project. Generic gotchas are noise. | | "I'll write 'good code quality' under Conventions as a placeholder." | Vague conventions are worse than no conventions. Stub it. | | "They said skip but I can tell from the repo that X is true." | Skip means skip. The user knows their project; if they skipped, it's because there's nothing non-obvious to say. | | "The example has 8 filled sections, theirs should too." | The example is for a mature, scarred-by-production codebase. A new project might fill 2 sections. That's correct. |

Red Flags — Stop and Recheck

If you find yourself:

• Reading the codebase to infer content for the file (vs. to identify questions)
• Suggesting wording before asking the question
• Filling a section because it "looks empty"
• Copying any specific Postlane content
• Telling the user a stubbed section is "incomplete"

Stop. You've drifted into assumption. Re-ask the user; if they say skip, stub it.

Files

• references/postlane-example.md — the one-shot, with framing for what to copy (structure, voice) vs. not copy (specifics)
• references/interview-questions.md — section-by-section question scripts
• templates/claude-md-stub.md — the empty template with TODO comments for each section