# Setup Claude

> Set up or audit Claude Code configuration in a repository, including CLAUDE.md, subagents, skills, MCP, settings, hooks, and Make targets.

- Skill: `xakki/setup-claude` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add xakki/setup-claude`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xakki/setup-claude/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Xakki (https://skillmd.com/u/xakki)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/xakki/setup-claude

---


# Setup Claude Code in this repository

Universal template, stack-agnostic. All artifacts live locally in the repo and under git.

## 1. Sources (mandatory — WebFetch before work)

Canonical domain: `code.claude.com/docs/en/*`. Full URL list with per-page descriptions → [reference.md](reference.md).

If 404 → `WebSearch site:code.claude.com <topic>`. Ignore third-party blogs.

## 2. Discovery — Phase 1 (no file writes)

1. `git log --oneline -30`, active branches, manifests (`package.json`, `composer.json`, `go.mod`, `Makefile`, `docker-compose.yml`)
2. Existing `CLAUDE.md` (managed → user → project), `.claude/rules/`, `.claude/agents/`, `.claude/skills/`, `.claude/commands/`, `.mcp.json`, `AGENTS.md`
3. README/CONTRIBUTING/TODO — extract **team process** and **no-touch zones** only
4. Stack map, monolith vs modules, legacy vs new; Makefile quality
5. Skip: `vendor/`, `node_modules/`, `*_data/`, `dist/`, `build/`, binaries

Report ≤ 30 lines: stacks, existing Claude config, proposed agents/skills/MCP/rules, Makefile plan, hook options (§4 below). **Wait for ok.** Alternative: suggest `/init` as starting point, then refine.

## 3. Deliverables — Phase 2 (after confirmation)

| Artifact | Key constraint |
|---|---|
| `CLAUDE.md` | ≤ 200 lines; only what can't be read from code; mandate `make <target>` for all ops |
| `.claude/rules/*.md` | Optional; use `paths:` frontmatter to scope to subtrees |
| `.claude/agents/*.md` | `name` + `description` required; explicit `tools:`; narrow scope |
| `.claude/skills/<name>/SKILL.md` | ≤ 500 lines; happy-path only; bulk detail → neighbor files |
| `.mcp.json` | Project-specific only; list in `enabledMcpjsonServers`; use `claude mcp add` |
| `.claude/settings.json` | Commit; `settings.local.json` → `.gitignore`; deny→ask→allow (first match) |
| `Makefile` | Required; create if absent; `make help` with `##@` groups; all ops via make |

Full frontmatter fields, settings.json template, and Makefile skeleton → [reference.md](reference.md).

## 4. Hooks — mandatory user ask

⚠️ **Never add hooks without explicit user consent.** After discovery, present:

```
[ ] PreToolUse + Bash: block rm -rf, git push --force, direct docker/npm bypassing make — low risk
[ ] PreToolUse + Edit|Write: block writes to .env*, vendor/, DB dumps — low risk
[ ] PostToolUse + Edit|Write: make lint after edits — medium risk (modifies code)
[ ] UserPromptSubmit: inject git status --short — low risk, +tokens
[ ] Stop / SubagentStop: Telegram/Slack notification for long tasks — low risk
[ ] SessionStart: inject make help — medium risk (+tokens)
[ ] InstructionsLoaded: log which CLAUDE.md/rules loaded — zero risk
Enable: <numbers> / none
```

Security: hooks in project-settings are git-shared → no credentials; use `$CLAUDE_PROJECT_DIR`; validate `tool_input` via `jq`. Full event list, handler types, exit codes → [reference.md](reference.md). **Default: no hooks.**

## 5. Definition of Done

- [ ] All frontmatter fields valid per official docs
- [ ] `CLAUDE.md` ≤ 200 lines; doesn't duplicate parent
- [ ] Agents: `name` + `description` mandatory; `tools:` explicit
- [ ] Skills: `.claude/skills/<name>/SKILL.md`; no new `.claude/commands/`
- [ ] `settings.json` committed; `settings.local.json` + `CLAUDE.local.md` in `.gitignore`
- [ ] `Makefile` exists; `make help` works with sections
- [ ] `CLAUDE.md` mandates `make <target>` for all operations
- [ ] Hooks agreed with user
- [ ] Test run: typical question ≤ 5 tool calls
- [ ] No reads of `vendor/`, `node_modules/`, DB dumps during setup
- [ ] Final report: files list, line counts, make targets added, hooks enabled

## 6. What NOT to do

- No "universal" agents — use `Explore`, `Plan`, `general-purpose`
- No README/docs copied into `CLAUDE.md`
- No MCP/skills/agents added "just in case"
- No hooks without explicit user ok
- No direct stack commands when a `make` target exists or can be added
- No new `.claude/commands/*.md` — use skills
- No `docs/architecture.md` created just for documentation
- No changes to project code (only Claude Code config + Makefile)