Gh

Source: gh.md (ingested 2026-03-28)

Claude Code Setup & Upgrade — Superprompt

Attached: claude-code-guide.jsx — use it as your reference for all .claude/ structure decisions.

Context

I'm running Claude Code from PowerShell on Windows. Before doing anything, orient yourself:

Print my current working directory
Confirm this is a git repository (or tell me if it isn't)
If I'm in a system directory (like System32, Program Files, Windows, etc.), STOP and tell me to cd into my actual project directory first — never write config to system paths

Your Mission

Act as my Claude Code infrastructure architect. You have three jobs, executed in order. Complete each phase fully before moving to the next. Never write or modify files without my explicit approval.

PHASE 1: Discovery & Audit

1A. Project-Level Scan

Find and inventory every governance/instruction file in this project:

CLAUDE.md (root + any subdirectories)
CLAUDE.local.md
.claude/ directory and ALL contents (settings.json, settings.local.json, commands/, skills/, agents/, rules/, hooks, .mcp.json)
Legacy files: .cursorrules, .github/copilot-instructions.md, AGENTS.md, .clinerules, CONVENTIONS.md

1B. Global Scan

Check my global config at ~/.claude/ (on Windows: %USERPROFILE%.claude):

CLAUDE.md — exists? contents?
settings.json — current permissions/hooks?
skills/ — any global skills?
commands/ — any global commands?
keybindings.json — custom keybindings?
projects/ — list projects with auto-memory, note stale ones

1C. Gap Analysis

Using the attached claude-code-guide.jsx as your reference for ideal structure, identify:

🔴 Broken or harmful — contradictory rules, stale commands, security issues, wrong paths 🟡 Upgrade candidates:

.claude/commands/*.md files that should migrate to skills/ (need bundled scripts, auto-invocation, or tool restrictions)
CLAUDE.md sections over 50 lines on one topic → extract to .claude/rules/
Style rules in CLAUDE.md that should be hooks instead (formatting, linting, import sorting)
Missing permissions or deny rules in settings.json 🟢 Missing but valuable — hooks, agents, skills, rules files that would help based on this project's stack ⚪ Dead weight — rules Claude already follows, duplicated instructions, stale references

Present Phase 1 findings as a structured report. Then STOP and wait for my input.

PHASE 2: Plan

Based on my feedback on Phase 1, create a concrete execution plan covering:

Project-Level Changes

CLAUDE.md — proposed content (aim for <200 lines, only what Claude can't infer from code)
- Use "Prefer X over Y" phrasing, not "Do not Y"
- Include: build/test/lint commands, architecture overview, hard rules
- Exclude: anything the linter handles, generic advice, personal preferences
settings.json — proposed permissions (allow/deny) and hooks
- PostToolUse hook for formatter (detect which one this project uses)
- PostToolUse hook for type checking if TypeScript
- Deny list for dangerous operations
.claude/rules/ — proposed modular rule files (only if CLAUDE.md topics need depth)
.claude/skills/ — proposed skills for repeatable workflows (with frontmatter)
- Add context: fork for skills that shouldn't pollute main context
- Add allowed-tools for read-only skills
.claude/agents/ — proposed subagents if this project benefits from isolated reviewers
Commands → Skills migration — for any existing commands that should upgrade
.gitignore additions — CLAUDE.local.md, .claude/settings.local.json

Global Changes (if needed)

~/.claude/CLAUDE.md — cross-project preferences (30-50 lines)
Global skills — 2-3 universally useful skills (commit, reflection, etc.)
Stale memory cleanup — prune dead projects from ~/.claude/projects/

Execution Order

Number every change. Group them as:

Phase 2A: Fix broken/harmful issues
Phase 2B: Migrate commands → skills
Phase 2C: Extract rules, add hooks
Phase 2D: Create new agents/skills
Phase 2E: Prune CLAUDE.md
Phase 2F: Global config updates
Phase 2G: Git hygiene (.gitignore, commit .claude/)

For each change, show me the EXACT content that will be written. Show diffs for modifications.

Present the full plan. Then STOP and wait for my approval. I may modify items before you proceed.

PHASE 3: Execute

After I approve (with any modifications):

Execute changes in the approved order
After each file write/modification, confirm what was done
After all project-level changes: re-read the complete config and flag any remaining contradictions
Show a before/after comparison: | File | Before (lines) | After (lines) | Action |
After all global changes: confirm what was written to ~/.claude/
Final verification: run a quick sanity check
- Can Claude find the build command?
- Do all referenced file paths exist?
- Are there any contradictions between CLAUDE.md and rules/?
- Is settings.json valid JSON?

Guiding Principles (from the attached reference)

CLAUDE.md is built through deletion, not addition. Start with /init output and subtract.
Only include what Claude cannot infer from reading code. If the linter enforces it, use a hook.
commands/ and skills/ have merged. New workflows go in skills/. Existing commands still work.
Skills are directories, not files. Each has a SKILL.md + optional scripts/templates.
Agents define WHO, skills define WHAT. A skill can reference an agent via frontmatter.
settings.json hooks must be fast (<2s). Slow hooks kill productivity.
Treat .claude/ like CI config. Commit it, review it in PRs, audit it in untrusted repos.
Global ~/.claude/ is for personal defaults. Never committed, applies to all projects.
CLAUDE.local.md and settings.local.json are gitignored. Personal overrides go here.
Target <200 lines per CLAUDE.md file. Extract depth into rules/.
Phrase rules as "Prefer X over Y" not "Do not Y." Claude respects positive framing more.