Multi-Project Setup

If you work on more than one repo with Claude Code, the kit gives you three levels of customization:

This recipe covers using all three coherently.

Step 1 — Install the kit in each repo

cd ~/projects/my-app
npx @tansuasici/claude-code-kit init

cd ~/projects/my-other-app
npx @tansuasici/claude-code-kit init

Each repo gets its own copy. They're independent — no shared state by default.

Step 2 — Identify what's shared vs project-specific

For each rule you have, ask:

Step 3 — Set up user-level rules

Personal preferences that follow you across projects belong in ~/.claude/CLAUDE.md (Claude Code's user-level config). Examples:

# ~/.claude/CLAUDE.md

## My Preferences

- I prefer responses under 400 words unless I ask for detail.
- Use tabs for Python (yes I know, fight me).
- Always squash on merge — never `--merge` strategy.
- When committing, prefix with conventional-commit type even on solo projects.

These load alongside any project's CLAUDE.md. They override kit defaults if there's a conflict (user-level > project > kit).

You can also keep user-level skills in ~/.claude/skills/ — same format as project skills, available everywhere.

Step 4 — Per-project overlays

Each repo's CLAUDE.project.md is independent. Keep them focused on what's actually different about that project:

# my-app/CLAUDE.project.md

## Project Context

Next.js 16 PWA, offline-first, Dexie for IndexedDB.

## Stack-Specific Rules

- Server Components first
- API uses envelope pattern

# my-other-app/CLAUDE.project.md

## Project Context

FastAPI backend with SQLAlchemy 2.0 and Pydantic v2.

## Stack-Specific Rules

- Async-first — every endpoint, every DB call
- Pydantic models in models/, never inlined

No coordination needed. They're separate files in separate repos.

Step 5 — Sharing lessons across projects

tasks/lessons.md is per-repo. If you learn something in one project that applies to others (e.g., "always use Promise.allSettled not Promise.all for fan-out"), three options:

Option A — Manually copy

Just copy the lesson to each repo's tasks/lessons.md. Simple. Works.

Option B — Promote to user-level

If the lesson is truly universal, move it to ~/.claude/CLAUDE.md under a "## Lessons" section. Now it's loaded everywhere.

Option C — Extract to a user-level skill

If the lesson keeps coming up and benefits from process/examples, write a skill at ~/.claude/skills/<name>/SKILL.md. Available across every project.

Step 6 — Coordinated upgrades

When the kit ships a new version (e.g., 1.7.2 → 1.8.0), upgrade each repo:

cd ~/projects/my-app && npx @tansuasici/claude-code-kit init --upgrade
cd ~/projects/my-other-app && npx @tansuasici/claude-code-kit init --upgrade

--upgrade only touches kit-managed files (listed in .kit-manifest). Your CLAUDE.project.md and agent_docs/project/ are never touched.

If you have a lot of repos and want this scripted:

# upgrade-all-kits.sh
for dir in ~/projects/*/; do
  if [ -f "$dir/.kit-manifest" ]; then
    echo "Upgrading $dir..."
    (cd "$dir" && npx @tansuasici/claude-code-kit init --upgrade)
  fi
done

Step 7 — Cross-tool export

If your team uses different AI tools (some on Claude Code, some on Cursor, some on Aider), generate cross-tool configs:

./scripts/convert.sh all

This produces:

• .cursorrules (Cursor)
• .windsurfrules (Windsurf)
• .aider.conf.yml (Aider)
• AGENTS.md (Linux Foundation cross-tool standard, supported by Copilot, Codex, Jules, etc.)

All derived from CLAUDE.md + CLAUDE.project.md. Source of truth stays in the kit. Don't edit .cursorrules etc. — re-run convert.sh after any kit change.

Add to your build / pre-commit:

{
  "scripts": {
    "kit:export": "./scripts/convert.sh all",
    "precommit": "pnpm run kit:export && git add .cursorrules .windsurfrules AGENTS.md"
  }
}

Step 8 — Optional: a "kit-of-kits" repo

If you have very strong opinions and use the kit on 10+ repos, consider:

1. Fork tansuasici/claude-code-kit to your own org

2. Add your defaults to CLAUDE.md, agent_docs/, .claude/skills/ directly in your fork

3. Each project installs from your fork:

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

This is heavier than user-level rules — only worth it if you have team-wide opinions and need them committed to git, not just on your laptop.

Verification

For each repo, run:

./scripts/doctor.sh   # confirms installation healthy
./scripts/validate-skills.sh  # confirms any custom skills are valid

In Claude Code, ask: "What kit version is this and what overlays are loaded?" — Claude should report the kit version (from .kit-manifest) and mention reading CLAUDE.project.md.

Common pitfalls

• Editing kit-managed files in one repo and forgetting in others — diverges your kits. Use --upgrade to re-sync.
• Treating tasks/lessons.md as user-level — it's per-repo. Promote universal lessons to ~/.claude/CLAUDE.md.
• Putting stack-specific rules in ~/.claude/CLAUDE.md — pollutes other projects. Use each repo's CLAUDE.project.md.
• Forgetting to re-run convert.sh — .cursorrules etc. drift. Make it a precommit hook.

Related

• Customize CLAUDE.project.md — what goes in the per-repo overlay
• Migrate from Cursor rules — if some of your repos still use Cursor
• CLAUDE.md guide — how the layered config loads