Claude Code Kit

Drop-in starter templates that make Claude Code behave like a disciplined staff engineer instead of an eager intern.

The Problem

Out of the box, Claude Code is powerful but undisciplined. It will:

• Start coding before understanding the codebase
• Make sweeping changes across files you didn't ask it to touch
• Skip verification steps and ship broken code
• Forget lessons from previous mistakes
• Install dependencies and change architecture without asking

The Solution

This kit provides a CLAUDE.md instruction set and supporting templates that enforce a structured workflow:

Plan > Confirm > Implement > Verify — every single time.

Quick Start

npx @tansuasici/claude-code-kit init

Or with curl:

curl -fsSL https://raw.githubusercontent.com/tansuasici/claude-code-kit/main/install.sh | bash

Or as a Claude Code plugin:

/plugin marketplace add tansuasici/claude-code-kit
/plugin install claude-code-kit@claude-code-kit

Then fill in CODEBASE_MAP.md with your project's details and start a Claude Code session.

Maintainers: see RELEASING.md for the release flow (npm token setup, 2FA mode requirement, EOTP recovery).

Installer options

Uninstall

curl -fsSL https://raw.githubusercontent.com/tansuasici/claude-code-kit/main/uninstall.sh | bash

Examples:

# Install with npx
npx @tansuasici/claude-code-kit init --template nextjs
npx @tansuasici/claude-code-kit init --profile strict
npx @tansuasici/claude-code-kit init --wiki
npx @tansuasici/claude-code-kit init --html
npx @tansuasici/claude-code-kit init --upgrade

# Or with curl
curl -fsSL .../install.sh | bash -s -- --template nextjs
curl -fsSL .../install.sh | bash -s -- --gitignore
curl -fsSL .../install.sh | bash -s -- --upgrade
curl -fsSL .../install.sh | bash -s -- --diff
curl -fsSL .../install.sh | bash -s -- --version v1.0.0

npx CLI commands

npx @tansuasici/claude-code-kit init              # Install kit
npx @tansuasici/claude-code-kit doctor            # Check installation health
npx @tansuasici/claude-code-kit skills            # List available /skill commands
npx @tansuasici/claude-code-kit convert all       # Export to Cursor/Windsurf/Aider/AGENTS.md + .agents/skills
npx @tansuasici/claude-code-kit convert codex     # Codex: AGENTS.md rules + .agents/skills
npx @tansuasici/claude-code-kit generate agents-md  # Generate AGENTS.md only
npx @tansuasici/claude-code-kit --version         # Show version

git clone --depth 1 https://github.com/tansuasici/claude-code-kit.git /tmp/cck
cp /tmp/cck/CLAUDE.md /tmp/cck/CODEBASE_MAP.md /tmp/cck/CLAUDE.project.md .
cp -r /tmp/cck/agent_docs /tmp/cck/tasks /tmp/cck/scripts /tmp/cck/.claude .
rm -rf /tmp/cck

What CLAUDE.md Enforces

Before / After

You: "Add a search feature to the users page"

Claude: *immediately starts coding*
  - Installs 3 new packages without asking
  - Refactors the entire users module "while it's here"
  - Breaks the build because it didn't typecheck
  - Doesn't test anything
  - You spend 30 minutes reviewing and reverting unrelated changes

You: "Add a search feature to the users page"

Claude: "Let me restate: add search functionality to the users page.
I've read CODEBASE_MAP.md — the users page is at app/(dashboard)/users/page.tsx,
data comes from src/services/user.service.ts.

This touches 3+ files, so here's my plan:"

  ## Task: Add search to users page
  ### Approach
  1. Add search param handling in users/page.tsx
  2. Add `searchUsers()` to user.service.ts
  3. Add search input component
  ### Files to Touch
  - app/(dashboard)/users/page.tsx
  - src/services/user.service.ts
  - components/features/user-search.tsx (new)

  "Should I proceed with this plan?"

You: "Yes"

Claude: *implements, then runs:*
  1. tsc --noEmit ✓
  2. eslint ✓
  3. npm test ✓
  4. Opens the page, verifies search works ✓

  "Done. All verification passed."

Hooks

Hooks are shell scripts that run automatically — unlike CLAUDE.md rules (advisory), hooks are deterministic. The kit ships 27 hooks; the standard profile wires up 23, and 4 are opt-in (they can be slow or conflict with project configs).

Guardrails — block on violation (PreToolUse / Stop):

Context & observability — inject or warn, never block:

Opt-in — not enabled by default:

See agent_docs/hooks.md for how to enable the opt-in hooks and write your own.

KitBench — hooks are tested

The hooks above aren't documentation, they're a contract. The kit ships bench/: a reproducible eval harness with 43 scenarios covering every blocking hook plus regression tests for past bugs (composer.lock slip-through, EXIT_CODE=$? after || true, .github/workflows/ci.yml basename-with-slash miss, word-boundary regex rejecting "authentication", stale quality-gate verdict blocking a fresh session). Run it any time with ./scripts/run-bench.sh; CI runs it on every PR.

KitBench
========================================
  s01-protect-files-blocks-env                      PASS
  s02-protect-files-blocks-composer-lock            PASS
  s03-protect-changes-blocks-package-json           PASS
  ...                                               PASS
========================================
  43/43 PASS  0 FAIL

Auto Mode

Claude Code's auto mode (claude --permission-mode auto, or Shift+Tab to it) auto-approves safe actions and stops only on the risky, irreversible ones — fewer prompts, without the blunt --dangerously-skip-permissions. The kit is the floor that makes it safe to turn on:

• The PreToolUse blocking hooks (protect-files, protect-changes, branch-protect, block-dangerous-commands) fire before the auto-mode classifier and hard-block on exit 2.
• The curated permissions.deny list (curl, wget, npm publish, cat .env*, …) resolves before the classifier and can't be overridden by it.

The classifier can only further restrict — never un-block — what the kit denies. A repo can't grant itself auto mode (defaultMode: "auto" is ignored in project settings), so you opt in at the user level:

claude --permission-mode auto

The same floor makes an unattended /loop (scheduled, in-session autonomy) safe: session-start re-fires each iteration to re-anchor the plan, and the deny hooks + stop-gate still hold on every action. The kit ships no loop.md on purpose — it's an inherently project-specific prompt, and the built-in maintenance loop already covers the generic case.

For the full precedence model, the strict posture (deny floor + disableBypassPermissionsMode), the /loop autonomy notes, and the classifier-tuning knobs, see agent_docs/auto-mode.md.

Agents

Built-in agents for code review, planning, and maintenance:

Skills

User-invocable audit and guide skills — run with /skill-name:

Stack Templates

Each template includes a customized CLAUDE.md with stack-specific rules and a pre-filled CODEBASE_MAP.md:

Auto-detected from your project files (next.config.*, go.mod, Cargo.toml, manage.py, requirements.txt, package.json) when --template is omitted.

Scripts

Status line setup

Add to .claude/settings.json:

{
  "statusLine": {
    "command": "./scripts/statusline.sh"
  }
}

sonnet-4.5 | feat/search | ████████░░ 78% | $1.24

Features

AGENTS.md Export — Generate a cross-tool AGENTS.md file from your project configuration. Compatible with GitHub Copilot, OpenAI Codex, Cursor, Google Jules, and Aider. Source of truth remains CLAUDE.md — AGENTS.md is a one-way derived output.

Cross-tool Skills Export — convert.sh skills mirrors the kit's skills into .agents/skills/<name>/SKILL.md, the shared Agent Skills location that Codex, Zed, and Amp all read (the Claude-only user-invocable key is stripped). convert.sh codex exports the discipline (as AGENTS.md rules) plus those skills in one step.

One-time Rules Import — adopting the kit on a project that already has Cursor/Windsurf/Copilot/Aider/AGENTS.md rules? convert.sh import collects them into tasks/imported-rules.md (frontmatter stripped, the kit's own generated exports skipped) for you to review and curate into CLAUDE.project.md. It never auto-edits your overlay. The kit's deterministic hooks do not port to Codex — its repo-local hooks are unreliable (openai/codex#17532) and the kit's hooks parse Claude Code's hook-JSON schema — so the discipline reaches Codex as rules, but the automatic enforcement stays Claude-Code-only.

Tiered Session Boot — Context loads in 3 tiers to minimize token overhead: Tier 1 (always: project map + overlay), Tier 2 (if continuing: handoff + todo), Tier 3 (on demand: lessons top rules, decisions). Reduces startup token cost ~40-50%.

npx Distribution — Install and manage the kit with npx @tansuasici/claude-code-kit init. Supports init, upgrade, doctor, convert, and generate commands.

Session Handoff — Long sessions lose context. Before ending, Claude generates tasks/handoff-[date].md. The next session reads it and resumes where you left off.

Skill Extraction — Claude discovers non-obvious things during sessions (framework quirks, workarounds, config gotchas). The skill system captures these as .claude/skills/<name>/SKILL.md files that load automatically via semantic matching. Run /skill-extractor to review.

Architecture Decision Records — When Claude presents options and you pick one, the reasoning gets recorded in tasks/decisions.md as ADRs with context, options, and consequences.

DESIGN.md — Optional design system template for UI projects. Captures colors, typography, spacing, component styles in a format agents read natively. The /design-review skill checks implementation against it.

Knowledge Wiki — Optional knowledge wiki module (install with --wiki). Based on Andrej Karpathy's LLM Wiki pattern: Claude incrementally builds and maintains a persistent, interlinked wiki from raw sources. Three operations: /wiki-ingest processes new sources into the wiki, /wiki-lint health-checks for contradictions and orphans, /wiki-briefing gives you a daily summary. The wiki compounds — every source you add makes it smarter.

HTML Artifacts — Optional module (install with --html). Based on the Claude Code team's pattern of preferring HTML output over markdown for specs, plans, PR writeups, reports, and design prototypes — richer information (SVG, tables, code, interactions), easier to share (upload + link), and easier to read for anyone outside your terminal. The kit ships ARTIFACTS.md (conventions) and a design-system.html reference so every generated artifact stays on-brand. Deliberately ships without a /html skill — the original recommendation is to just prompt for HTML, not to over-structure it.

Product Context — Optional templates in agent_docs/project/ (mission.md, tech-stack.md, roadmap.md) give agents product awareness beyond code conventions.

Permissions — .claude/settings.json includes curated allow/deny lists. Allowed: test runners, linters, git reads. Denied: curl, wget, .env reads, npm publish. Review and customize for your project.

Project Overlay — Separate kit-managed files from project-specific customizations. CLAUDE.project.md, agent_docs/project/, and .claude/hooks/project/ are never touched by kit upgrades, so your project rules survive --upgrade cleanly.

What's Inside

claude-code-kit/
  CLAUDE.md                        # Core agent instructions (kit-managed)
  CLAUDE.project.md                # Project-specific overlay (yours, never overwritten)
  CODEBASE_MAP.md                  # Project mapping template
  AGENTS.md                        # Cross-tool standard (generated by gen-agents-md.sh)
  package.json                     # npm package definition (for npx distribution)
  .kit-manifest                    # Tracks kit-managed files (auto-regenerated by scripts/sync-manifest.sh; CI fails if stale)
  install.sh                       # One-line setup script
  uninstall.sh                     # Clean removal script
  bin/
    claude-code-kit.js             # Node.js entry point for npx
    cli.sh                         # Shell CLI implementation
  agent_docs/                      # Agent behavior guides
    workflow.md                    #   Planning templates & task lifecycle
    debugging.md                   #   4-step debugging protocol
    testing.md                     #   Test strategy & patterns
    conventions.md                 #   Naming, structure, git hygiene
    subagents.md                   #   When & how to use subagents
    hooks.md                       #   Hooks guide & how to write your own
    skills.md                      #   Skill extraction guide
    contracts.md                   #   Task contract system
    prompting.md                   #   Bias awareness & neutral prompting
    architecture-language.md       #   Vocabulary for /deepening-review and /interface-design
    project/                       #   Project-specific docs (yours)
  tasks/                           # Session state & tracking
    todo.md, decisions.md, handoff.md
    lessons/                       #   Per-file lessons (YAML frontmatter)
      _index.md                    #     Top Rules + per-lesson links
      _TEMPLATE.md                 #     Template for new lessons
      <YYYY-MM-DD>-<slug>.md       #     One file per lesson
  scripts/                         # Utility scripts
    doctor.sh, validate.sh, statusline.sh, convert.sh, validate-skills.sh, build-skills.sh, gen-skill-docs.sh, gen-agents-md.sh
  # --- Optional: Knowledge Wiki (--wiki) ---
  WIKI.md                          # Wiki schema & conventions
  raw-sources/                     # Immutable source documents (yours)
  wiki/                            # Claude-maintained knowledge base
    index.md, log.md               # Navigation & activity log
    summaries/, entities/, concepts/ # Wiki page directories
  # --- Optional: HTML Artifacts (--html) ---
  ARTIFACTS.md                     # HTML artifact conventions & schema
  artifacts/                       # Generated HTML artifacts
    design-system.html             # Reference tokens — every artifact mirrors these
    index.html                     # Catalog of all artifacts
  .claude/
    settings.json                  # Hook configs & permissions
    agents/                        # code-reviewer, security-reviewer, planner, qa-reviewer, dead-code-remover, wiki-maintainer
    hooks/                         # 22 deterministic hook scripts (lib/ shared helpers)
      project/                     # Project-specific hooks (yours)
    skills/                        # Reusable knowledge & audit skills
      _shared/blocks/              # Shared template blocks (preamble, scope, etc.)
      _templates/                  # .tmpl skill templates (source of truth)
      skill-extractor/             # Meta-skill for knowledge extraction
      skill-generator/             # Meta-skill for generating project skills
      code-quality-audit/          # Code smells & error handling audit
      performance-audit/           # Bottleneck & rendering analysis
      architecture-review/         # SOLID & module boundary review
      deepening-review/            # Depth/seam paradigm — interactive candidate grilling
      interface-design/            # Design It Twice — parallel competing interfaces
      testing-audit/               # Test coverage & quality audit
      dead-code-audit/             # Unused code detection
      refactoring-guide/           # Fowler-based refactoring plans
      accessibility-audit/         # WCAG 2.1 AA compliance
      dependency-audit/            # Vulnerability & license checks
      documentation-audit/         # Doc quality & sync audit
      doc-gardening/               # Docs↔code drift detection
      project-health-report/       # Comprehensive health report
      review-pipeline/             # Parallel multi-audit review (PR-scope)
      quality-audit/               # golden-principles.yaml drift audit
      constitution/                # Author/extend golden-principles.yaml
      references-sync/             # Sync llms.txt-style dependency refs
      harness-init/                # Scaffold docs/ harness structure
      feature-cycle/               # End-to-end lifecycle orchestrator
      lesson-refresh/              # Periodic tasks/lessons/ refresh
      lesson-resurface/            # Surface dormant lessons by topic
      pulse/                       # Time-windowed outcome report
      scorecard/                   # Session-telemetry scorecard
      note/                        # Session-journal note (across compaction)
      ship/                        # Deployment pipeline
      retro/                       # Sprint retrospective & analytics
      office-hours/                # Pre-coding product validation
      debug/                       # Root-cause debugging
      design-review/               # UI design consistency review
      ui-component-builder/        # Production-ready UI component generator
      shape-spec/                  # Feature spec folder creation
      wiki-ingest/                 # Wiki source ingestion (--wiki)
      wiki-lint/                   # Wiki health checks (--wiki)
      wiki-briefing/               # Wiki daily briefing (--wiki)
  examples/
    nextjs/                        # Next.js 16 + App Router template
    node-api/                      # Express + TypeScript template
    python-fastapi/                # FastAPI + SQLAlchemy template

Project Overlay

The kit separates kit-managed files (updated by --upgrade) from project-specific files (never touched):

Project rules in CLAUDE.project.md override kit defaults. Add project-specific docs (offline-first patterns, SignalR conventions, etc.) to agent_docs/project/ and project-specific hooks to .claude/hooks/project/.

The .kit-manifest file tracks which files are kit-managed, so upgrades know what to update and what to skip.

Customization

This kit is a starting point. You should:

1. Fill in CODEBASE_MAP.md — the more detail, the better Claude performs
2. Customize CLAUDE.project.md — add project-specific rules, constraints, and patterns
3. Add project docs — put stack-specific guides in agent_docs/project/
4. Track lessons — tasks/lessons/ compounds over time (one file per lesson, with YAML frontmatter and a Top Rules index), making Claude smarter per-project

Contributing

PRs welcome. If you've built a template for a stack we don't cover yet, open a PR.

License

MIT