claude-code-ultimate-guide/claude-setup-audit-prompt.md

Audit Your Claude Code Setup

A self-contained prompt to analyze your Claude Code configuration against best practices.

Author: Florian BRUNIAUX | Founding Engineer @Méthode Aristote

Reference: The Ultimate Claude Code Guide

---

1. What This Does

This prompt instructs Claude to perform a comprehensive audit of your Claude Code setup by:

1. Scanning your global and project configuration files (read-only)
2. Evaluating each element against best practices from the guide
3. Generating a prioritized report with actionable recommendations
4. Providing ready-to-use templates tailored to your tech stack

Important: Claude will NOT make any changes without your explicit approval.

---

2. Who This Is For

Level	What You'll Get
Beginner	Discover what you're missing and get starter templates
Intermediate	Identify optimization opportunities and advanced patterns
Power User	Validate your setup and find edge cases to polish

Prerequisites:

• Claude Code installed and working
• A project directory to analyze (or just global config)

Time: ~5-10 minutes depending on setup complexity

---

3. How to Use It

Step 1: Copy the Prompt

Copy everything inside the code block in Section 4 below.

Step 2: Run Claude Code

cd your-project-directory
claude --ultrathink

Note

: --ultrathink enables maximum analysis depth (~32K tokens). You can also use --think for lighter analysis.

Step 3: Paste and Execute

Paste the prompt and press Enter. Claude will begin the audit.

Step 4: Review Results

Claude will present findings and ask for validation before making any changes.

Platform Note

Platform	Global Config Path
macOS/Linux	~/.claude/
Windows	%USERPROFILE%\.claude\

---

4. The Prompt

# Audit My Claude Code Setup

## Context

Perform a comprehensive audit of my Claude Code configuration against best practices from "The Ultimate Claude Code Guide":
https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/english-ultimate-claude-code-guide.md

## Instructions

### Phase 1: Discovery (Read-Only)

**IMPORTANT**: Only READ files. Do NOT modify anything.

#### 1.1 Detect Tech Stack (MANDATORY)

First, identify the project's technology stack by reading:
- `package.json` (Node.js/JavaScript/TypeScript)
- `requirements.txt` or `pyproject.toml` (Python)
- `go.mod` (Go)
- `Cargo.toml` (Rust)
- `composer.json` (PHP)
- `Gemfile` (Ruby)
- `pom.xml` or `build.gradle` (Java)

Store the detected stack for template customization later.

#### 1.2 Scan Configuration Files

**Global configuration** (`~/.claude/` or `%USERPROFILE%\.claude\` on Windows):
- `CLAUDE.md` (global memory)
- `settings.json` (global settings)
- `mcp.json` (MCP servers)
- `.claude.json` (permissions, allowedTools)

**Project configuration** (current directory):
- `./CLAUDE.md` (project memory - root level)
- `./.claude/CLAUDE.md` (local memory - gitignored)
- `./.claude/settings.json` (hooks configuration)
- `./.claude/settings.local.json` (local permissions)
- `./.claude/agents/` (custom agents)
- `./.claude/commands/` (custom commands)
- `./.claude/skills/` (knowledge modules)
- `./.claude/hooks/` (hook scripts)
- `./.claude/rules/` (auto-loaded rules)

**Project context**:
- Documentation folder: `docs/`, `docs/conventions/`, `documentation/`
- Test configuration: presence of test framework config

#### 1.3 Error Handling Rules

| Scenario | Behavior |
|----------|----------|
| File doesn't exist | Mark as ❌ Missing in report |
| File exists but empty | Mark as ⚠️ Empty (different from missing) |
| JSON parse error | Mark as ⚠️ Malformed, note the error |
| Permission denied | Note in report, skip file |
| Monorepo detected | Analyze root config, note per-package opportunities |

### Phase 2: Evaluate & Report

#### 2.1 Evaluation Checklist

For each category, evaluate against these criteria:

**Memory Files (Guide Section 3.1)**
- [ ] Global CLAUDE.md exists with personal preferences
- [ ] Project CLAUDE.md exists with team conventions
- [ ] Memory files are concise (not essays)
- [ ] Includes concrete examples
- [ ] References external docs instead of duplicating

**Single Source of Truth (Guide Section 3.1)**
- [ ] Conventions documented in `/docs/conventions/` or similar
- [ ] CLAUDE.md references these docs with `@path`
- [ ] Same conventions used across tools (CodeRabbit, SonarQube, etc.)

**Folder Structure (Guide Section 3.2)**
- [ ] `.claude/` folder properly organized
- [ ] Appropriate gitignore (settings.local.json, local CLAUDE.md)

**Context Management (Guide Section 2.2)**
- [ ] Awareness of context zones (green/yellow/red)
- [ ] Sanity markers strategy documented
- [ ] Context poisoning prevention considered

**Plan Mode Usage (Guide Section 2.3)**
- [ ] Plan mode mentioned for complex/risky tasks
- [ ] Auto Plan Mode configured if needed

**Agents (Guide Section 4)**
- [ ] Custom agents for repetitive specialized tasks
- [ ] Agents have clear descriptions (Tool SEO principle)
- [ ] Appropriate model selection per agent (haiku/sonnet/opus)

**Skills (Guide Section 5)**
- [ ] Reusable knowledge modules for complex domains
- [ ] Properly structured with frontmatter

**Commands (Guide Section 6)**
- [ ] Custom commands for frequent workflows
- [ ] Use $ARGUMENTS for flexibility

**Hooks (Guide Section 7)**
- [ ] Security hooks (PreToolUse) for sensitive operations
- [ ] Auto-formatting hooks (PostToolUse) if needed
- [ ] Context enrichment (UserPromptSubmit) if useful

**MCP Servers (Guide Section 8)**
- [ ] Serena configured if large codebase (indexation + memory)
- [ ] Context7 configured if using external libraries
- [ ] Other relevant MCPs for the project needs

**Think Levels & Trinity (Guide Section 9.1)**
- [ ] Understanding of --think / --think-hard / --ultrathink
- [ ] Trinity pattern documented for complex workflows

**CI/CD Integration (Guide Section 9.3)**
- [ ] Verify Gate pattern implemented (build → lint → test → typecheck)
- [ ] Autonomous retry loop considered

**Continuous Improvement (Guide Section 9.10)**
- [ ] Meta-rules for fixing system, not just code
- [ ] Learning from repeated issues

#### 2.2 Calculate Health Score

**Formula**: `Score = (earned_points / max_points) × 100`

| Priority | Points per ✅ | Weight Rationale |
|----------|--------------|------------------|
| 🔴 High | 3 points | Fundamentals, security, major productivity |
| 🟡 Medium | 2 points | Best practices, recommended patterns |
| 🟢 Low | 1 point | Polish, optimization, nice-to-have |

**Priority Assignment Rules**:
- 🔴 **High**: Missing CLAUDE.md (any), no security hooks, no permissions config, no context management awareness
- 🟡 **Medium**: No custom agents for repeated tasks, incomplete MCP setup, missing Single Source of Truth, no CI integration
- 🟢 **Low**: Tool SEO optimization, optional skills, advanced patterns like Trinity

#### 2.3 Generate Report

**Executive Summary** (5-10 lines):
- Health Score: X/100 (with color indicator)
- Top 3 Quick Wins (< 5 min each)
- Top 3 Important Gaps
- Detected tech stack

**Quick Wins Section**:
List 3-5 high-impact actions that take less than 5 minutes:

⚡ Quick Win 1: [action] → [impact] ⚡ Quick Win 2: [action] → [impact] ⚡ Quick Win 3: [action] → [impact]

**Findings Table** (4 columns):

| Priority | Element | Status | Action |
|----------|---------|--------|--------|
| 🔴 | ... | ❌/⚠️/✅ | ... |

**Detailed Findings** (expandable per item):
For each ❌ or ⚠️ item, provide:

[Element Name]

Current State: [what exists or doesn't] Why It Matters: [impact on workflow] Guide Reference: Section X.X

**Suggested Templates**:
For each High/Medium priority gap, provide a STACK-SPECIFIC template:

Template: [Element Name]

File: path/to/file Stack: [detected stack]

Suggested content: ``` [template content customized for the detected tech stack] ```

### Phase 3: Await Validation

**CRITICAL**: Do NOT create or modify any files without explicit approval.

After presenting the report, ask:

"Which of these suggestions would you like me to implement?

Options:
- `all` - Implement all templates
- `high` - Only 🔴 High priority items
- `1, 3, 5` - Specific items by number
- `none` - Just keep the report for reference

Please specify your choice:"

Wait for explicit user response before taking any action.

## Output Format

Structure your response exactly as:

1. **Executive Summary** (health score, quick wins, gaps, stack)
2. **Quick Wins** (3-5 immediate actions)
3. **Findings Table** (4-column overview)
4. **Detailed Findings** (expanded per item)
5. **Suggested Templates** (stack-specific, ready to use)
6. **Validation Request** (ask before implementing)

---

5. What to Expect

Here's an example of what the audit report looks like:

Example Executive Summary

## Executive Summary

**Health Score**: 45/100 🟡

**Detected Stack**: TypeScript + Next.js + Prisma

**Quick Wins** (< 5 min each):
⚡ Create project CLAUDE.md → Immediate context for Claude
⚡ Add .claude/ to .gitignore patterns → Prevent accidental commits
⚡ Enable Context7 MCP → Better library documentation

**Top 3 Gaps**:
1. 🔴 No project CLAUDE.md - Claude lacks project context
2. 🔴 No security hooks - Sensitive operations unprotected
3. 🟡 No custom agents - Repetitive tasks done manually

Example Findings Table

Priority	Element	Status	Action
🔴 High	Project CLAUDE.md	❌ Missing	Create with stack conventions
🔴 High	Security hooks	❌ Missing	Add PreToolUse for secrets
🟡 Medium	Custom agents	❌ Missing	Create for code review, testing
🟡 Medium	MCP Serena	⚠️ Partial	Add memory configuration
🟢 Low	Tool SEO	⚠️ Partial	Improve agent descriptions

---

6. Understanding Results

Glossary

Term	Definition
Memory Files	CLAUDE.md files that provide persistent context to Claude across sessions
Single Source of Truth	Pattern where conventions are documented once and referenced everywhere
Tool SEO	Writing agent/command descriptions so Claude selects the right tool automatically
MCP Servers	Model Context Protocol - external tools that extend Claude's capabilities
Serena	MCP server for codebase indexation and session memory persistence
Context7	MCP server for official library documentation lookup
Hooks	Scripts that run automatically on Claude events (PreToolUse, PostToolUse, etc.)
PreToolUse	Hook that runs BEFORE Claude executes a tool - great for security checks
PostToolUse	Hook that runs AFTER Claude executes a tool - great for formatting
Plan Mode	Read-only exploration mode for safe analysis before making changes
Think Levels	--think, --think-hard, --ultrathink - different analysis depths
Trinity Pattern	Combining Plan Mode + Think Levels + MCP for complex tasks
Verify Gate	CI/CD pattern: build → lint → test → typecheck before merge
Context Zones	Green (0-50%), Yellow (50-70%), Red (70%+) - context usage thresholds

Priority Levels Explained

Level	Meaning	Examples
🔴 High	Missing fundamentals, security risks, major productivity loss	No CLAUDE.md, no security hooks
🟡 Medium	Recommended best practices, significant improvements	No agents, incomplete MCP
🟢 Low	Nice-to-have optimizations, polish	Tool SEO, advanced patterns

Status Icons

Icon	Meaning
✅	Good - meets best practices
⚠️	Partial - exists but needs improvement
❌	Missing - doesn't exist or broken

---

7. Common Issues

"Claude didn't find my files"

Cause: Wrong working directory or platform path differences.

Fix:

• Ensure you run claude from your project root
• On Windows, paths use %USERPROFILE%\.claude\ not ~/.claude/

"Health score seems wrong"

Cause: The weighted formula may not match your priorities.

Fix: Focus on the specific findings rather than the score. The score is indicative, not absolute.

"Templates don't match my stack"

Cause: Stack detection failed or project uses uncommon setup.

Fix: Tell Claude your stack explicitly: "My project uses [X]. Regenerate templates for this stack."

"Too many recommendations"

Cause: First-time audit on a project without Claude Code configuration.

Fix:

1. Start with Quick Wins only
2. Implement High priority items first
3. Add Medium/Low items incrementally

"Claude made changes without asking"

Cause: This shouldn't happen if using the prompt correctly.

Fix:

• Ensure you copied the entire prompt including Phase 3
• Use Plan Mode (Shift+Tab twice) for extra safety
• Report this as a bug if it persists

---

8. Related Resources

• The Ultimate Claude Code Guide - Full reference
• Cheatsheet - Quick daily reference
• Claude Code Official Docs - Anthropic documentation

---

Last updated: January 2025 | Version 1.0