init

Initialize Project for Claude Code

File semantics

Three classes govern every file this skill writes. Later steps name the class instead of restating the rules.

• Generated — .claude/hooks/* and .claude/docs/coding-guidelines.md: verbatim templates (or fallback hooks), never user-authored. Always overwrite silently, regardless of audit status.
• Customizable — all CLAUDE.md files, testing.md, styling.md, architecture.md, skill-writing-guidelines.md: never silently overwrite. When the file exists, review-and-propose — compare against the template and detected state, apply only user-approved changes, preserve user-added sections.
• settings.json — always merge, never overwrite: preserve permissions and any other custom sections. Do not create it when no hooks are installed and it doesn't already exist.

New files of any class are written directly — no confirmation prompts. Preserve when unsure: content not derivable from the codebase is never discarded, not even to meet size targets. Mark content outdated only when source code directly contradicts it, and confirm with the user before removing user-added items. The same semantics apply to subproject docs in monorepos and to each repo's .claude/ in multi-repo workspaces.

CLAUDE.md authoring rules

CLAUDE.md is loaded into every conversation, and Claude can already read the repository. So the budget goes to what reading the repository does not give it.

• Spend it on gotchas. Invariants a script or CI depends on, a command that must run from a specific directory, a file that looks editable but is generated, a convention the code deliberately breaks in one place, setup that fails in a non-obvious way, why a decision was made. Write fewer real ones rather than padding to a count — an empty Gotchas section is a valid outcome, and better than five lines of restated obviousness.
• Never restate what the filesystem shows. No directory listings, no "the stack is TypeScript" when package.json says so, no per-file roles. One line of identity and stack at the top is the whole allowance.
• Commands do belong here: which of a dozen scripts is the real build/test/lint entry point, with the detected package-manager prefix, is not inferable.
• Target <= 60 lines. The limit is soft: condense template-generated content first; if user-added content still pushes it over, exceed the limit and note the overage in the Step 7 summary.
• Only universally-applicable content — task-specific material distracts the model and degrades instruction-following.
• Progressive disclosure: the Documentation table routes a kind of change to the one doc that governs it, so a typo fix does not load the architecture doc.
• file:line references, not code snippets — snippets go stale.
• No code-style rules — the formatter hooks installed in Step 5 enforce style deterministically.
• Monorepo: root CLAUDE.md is an orchestrator — subproject table, workspace-wide commands, workspace-level gotchas only; each subproject's own CLAUDE.md is auto-discovered when working there and carries that package's gotchas. Shared guidelines stay at root .claude/docs/; testing.md/styling.md/architecture.md are scoped per subproject.
• Multi-repo workspace: each repo is fully self-contained (own .claude/); the parent CLAUDE.md is a lightweight local-only map — nothing is shared at root.