# SETUP.md — Bootstrap a Claude Code config You're helping the user set up their `CLAUDE.md`, basic settings, and first skill. Derive everything from their existing work and context; ask only when you can't infer. ## Ground rules - **Start small.** First `CLAUDE.md` is 15-30 lines. It grows through use; a 100-line config on day one is speculation, not calibration. - **Every rule needs a source.** Derive rules from files they've written, past corrections, or things they tell you. If you can't point to where a rule came from, cut it. - **Corrections over adjectives.** "Don't restate the question before answering" beats "be concise." Push from preference to the specific thing they'd fix. - **Augment, don't replace.** If config exists, read it first and propose additions. Never overwrite without asking. - **One skill, or zero.** Derived from something they actually did. A skill built from speculation is worse than no skill. - **Show before writing.** Draft each file inline, get a thumbs-up, then write it. ## Step 1: Look around ```bash ls -la ~/.claude/ 2>/dev/null && cat ~/.claude/CLAUDE.md 2>/dev/null ls ~ && ls -d ~/code ~/src ~/projects ~/dev ~/work 2>/dev/null cat ~/.gitconfig 2>/dev/null git log --oneline -15 2>/dev/null && git diff --stat HEAD~5 2>/dev/null ls ~/.claude/projects/ 2>/dev/null ``` From this, figure out: - **Layout.** Where code lives, where docs/notes live, whether there's a convention. - **Stack.** Languages, frameworks, tools — from gitconfig, file extensions, what's on PATH. - **Style.** Read 2-3 files they wrote recently (not generated, not vendored). Note formatting, naming, structure, comment density. - **Current work.** What they were doing when they started this session, from git log, the working directory, and the conversation so far. **Mine past corrections.** If `~/.claude/projects/` has transcripts, search the user turns for correction signals — `actually`, `instead`, `don't`, `shouldn't`, `can you also`, `did you check`, `still`, `wrong`, `stop`. Group by pattern, show the most common, and ask: "Do any of these recur?" Those become `` rules. If there are no transcripts, ask one question: "What do you keep having to correct when working with Claude? Give me 2-3 examples." Don't write the config until you have at least two real corrections. ## Step 2: Draft CLAUDE.md ```markdown # CLAUDE.md name: ... role: ... stack: ... code lives in: ... docs/notes live in: ... - - - When unsure, . - When you disagree with my approach, . - = - ``` Every `` line must trace to a correction or stated preference. Omit sections you have nothing for. Don't include generic best practices, things Claude does by default, or rules for tools they don't use. Show the draft, confirm, write to `~/.claude/CLAUDE.md`. ## Step 3: Settings Merge into `~/.claude/settings.json`; create if missing, don't clobber existing hooks. **Stop hook** — plays a sound when a session finishes, so they can switch away and come back: ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "if command -v afplay >/dev/null 2>&1; then afplay /System/Library/Sounds/Glass.aiff; else tput bel; fi" } ] } ] } } ``` **Post-edit hook** — auto-formats on write, so diffs stay limited to real changes. Only offer if they code in a language with a fast formatter that's installed (`command -v ruff`, `prettier`, `gofmt`, `rustfmt`). Adapt the extension and command: ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.py) ruff format \"$f\" 2>/dev/null; ruff check --fix \"$f\" 2>/dev/null ;; esac; true" } ] } ] } } ``` **Permissions allow-list** — lets Claude run safe commands without prompting on every call. Same sourcing rule as `CLAUDE.md`: only allow what you saw them use in step 1. Start with read-only commands, their formatter, and their test runner. Don't allow writes, deletes, `git push`, or network calls — those should still prompt. ```json { "permissions": { "allow": [ "Bash(ls:*)", "Bash(cat:*)", "Bash(grep:*)", "Bash(rg:*)", "Bash(find:*)", "Bash(head:*)", "Bash(tail:*)", "Bash(wc:*)", "Bash(git log:*)", "Bash(git diff:*)", "Bash(git status:*)", "Bash(git show:*)", "Bash(ruff:*)", "Bash(pytest:*)" ] } } ``` Swap the last two lines for their actual formatter and test runner. If step 1 didn't show a test runner, leave it out — add permissions when the need is real, same as `CLAUDE.md` rules. ## Step 4: Connect to org context Local files are half the picture. MCP servers let Claude read Slack, Drive, GitHub, and similar — which is where most of an org's context actually lives. From step 1, you know what tools they use. Map each to an MCP server and propose only those. Don't install MCPs for tools they don't use. | Tool signal (from step 1) | MCP to propose | |---|---| | `.git` / GitHub remotes | `github` | | Slack mentioned in files/workflow | `slack` | | Google Docs/Sheets links | `google-workspace` or `gdrive` | | Notion links | `notion` | | Linear/Jira references | `linear` / `atlassian` | For each one they confirm, run `claude mcp add ` and follow the prompts. Tell them upfront: - **OAuth is on them.** Most MCPs open a browser for auth; Claude can't click through it. Expect a browser handoff per server. - **Tokens never go in config files.** If a server wants a token pasted into `mcp.json`, point them at the server's docs for a safer auth flow instead. - **Verify each one.** After connecting, run `claude mcp list` or call a read-only tool (e.g., list recent Slack channels). A silently failing MCP looks like Claude being unhelpful, not like a broken tool. If they're short on time, connect one — whichever tool holds the most context they'd otherwise paste by hand — and come back for the rest. ## Step 5: First skill Candidate: the task they were doing when they started this session, or the most recent multi-step task visible in the transcript or git log. Propose it: "You just did X — would you do that again next week?" Don't ask them to invent a candidate. If nothing qualifies, skip. Tell them to come back after doing a repeatable task once with Claude and ask Claude to turn it into a skill. Write `~/.claude/skills//SKILL.md`: ```markdown --- name: description: --- # / ## Steps 1. 2. 3. ``` Steps come from what they did, not what you'd design. Keep it under 40 lines. If the procedure branches, name the branch. Tell them the refinement loop: when the output is off, correct it in-session, then say "update the skill with what we fixed." ## Step 6: Verify Tell them to open a fresh session: 1. "What's in my CLAUDE.md?" — confirms it loads. 2. Do a small task; check the behavioral rules hold and the allow-list works. 3. Ask Claude to read something from a connected MCP — confirms auth held. 4. Trigger the skill by describing the task, not naming it — confirms the description routes. 5. Note what's off. That's the next round of edits. ## Done - `CLAUDE.md`: 15-30 lines, every line sourced. - `settings.json`: stop hook, formatter if they code, allow-list for what they actually run. - At least one MCP connected, or a note of which to set up next. - One skill, or deliberately none. - They know the loop: correct in-session, fold into config. If it took over 30 minutes, you over-built.