feat: add audit prompt and enhance guide with advanced patterns
- Add claude-setup-audit-prompt.md: self-contained prompt for setup analysis - 3-phase audit: Discovery → Evaluate & Report → Validation - Weighted health score formula (High=3, Med=2, Low=1 points) - Stack detection for contextual templates - Glossary of terms for beginners - Cross-platform paths (Unix + Windows) - Integrate Nick Tune's workflow patterns: - Section 3.1: Single Source of Truth pattern - Section 7.1: Shell Scripts vs AI Agents decision framework - Section 9.3: Verify Gate pattern with autonomous retry loop - Section 9.10: NEW Continuous Improvement Mindset - Add Community Resources section: - 5 awesome-* repos with descriptions - SuperClaude framework documentation - Learning sites (Claudelog, Official Docs) - Update README with: - Audit tool in What's Inside table - Dedicated "Audit Your Setup" section - Resources section with community links Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
729a90f1f4
commit
28b01c4dfe
3 changed files with 775 additions and 3 deletions
41
README.md
41
README.md
|
|
@ -35,6 +35,7 @@ If you find value in this guide, have questions, or want to discuss Claude Code
|
|||
|------|-------------|--------------|
|
||||
| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (4000+ lines) | ~2.5 hours |
|
||||
| [`cheatsheet-en.md`](./cheatsheet-en.md) | 1-page printable daily reference | 5 minutes |
|
||||
| [`claude-setup-audit-prompt.md`](./claude-setup-audit-prompt.md) | Self-audit prompt for your setup | ~10 minutes |
|
||||
| [`claude-code-ultimate-guide_notebooklm.pdf`](./claude-code-ultimate-guide_notebooklm.pdf) | Audio Deep Dive (NotebookLM podcast) | ~1 hour |
|
||||
| [`claude-code-ultimate-guide_kimi.pdf`](./claude-code-ultimate-guide_kimi.pdf) | PDF version (Kimi export) | ~2.5 hours |
|
||||
|
||||
|
|
@ -132,10 +133,46 @@ Found an error? Have a suggestion? Open an issue or PR.
|
|||
|
||||
---
|
||||
|
||||
## Audit Your Setup
|
||||
|
||||
Want to know if your Claude Code setup follows best practices?
|
||||
|
||||
**File**: [`claude-setup-audit-prompt.md`](./claude-setup-audit-prompt.md)
|
||||
|
||||
**How it works**:
|
||||
1. Copy the prompt from the file
|
||||
2. Run `claude --ultrathink` in your project
|
||||
3. Paste the prompt and get a personalized audit report
|
||||
|
||||
**What it checks**:
|
||||
- Memory files (CLAUDE.md) configuration
|
||||
- Agents, skills, commands, and hooks setup
|
||||
- MCP servers configuration
|
||||
- Context management practices
|
||||
- CI/CD integration patterns
|
||||
|
||||
**Output**: A prioritized report with health score, quick wins, and ready-to-use templates tailored to your tech stack.
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
|
||||
- [Claudelog.com](https://claudelog.com/) — Advanced tips & patterns (inspiration for some sections)
|
||||
### Official
|
||||
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) — Official Anthropic docs
|
||||
|
||||
### Community Curated Lists
|
||||
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Commands, workflows, IDE integrations
|
||||
- [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) — Custom skills collection
|
||||
- [awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) — Full-stack & DevOps subagents
|
||||
- [awesome-claude](https://github.com/alvinunreal/awesome-claude) — General Claude resources (SDKs, tools)
|
||||
- [awesome-claude-prompts](https://github.com/langgptai/awesome-claude-prompts) — Prompt templates
|
||||
|
||||
### Frameworks & Tools
|
||||
- [SuperClaude](https://github.com/SuperClaude-Org/SuperClaude_Framework) — Advanced configuration framework with 30+ commands
|
||||
- [Claudelog.com](https://claudelog.com/) — Tips, patterns & tutorials
|
||||
|
||||
### Further Reading
|
||||
- [Nick Tune: Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa) — Advanced autonomous workflow patterns
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
417
claude-setup-audit-prompt.md
Normal file
417
claude-setup-audit-prompt.md
Normal file
|
|
@ -0,0 +1,417 @@
|
|||
# Audit Your Claude Code Setup
|
||||
|
||||
> A self-contained prompt to analyze your Claude Code configuration against best practices.
|
||||
|
||||
**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
|
||||
|
||||
**Reference**: [The Ultimate Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/english-ultimate-claude-code-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 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](#4-the-prompt) below.
|
||||
|
||||
### Step 2: Run Claude Code
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```markdown
|
||||
# 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](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/english-ultimate-claude-code-guide.md#section-anchor)
|
||||
```
|
||||
|
||||
**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](./english-ultimate-claude-code-guide.md) - Full reference
|
||||
- [Cheatsheet](./cheatsheet-en.md) - Quick daily reference
|
||||
- [Claude Code Official Docs](https://docs.anthropic.com/en/docs/claude-code) - Anthropic documentation
|
||||
|
||||
---
|
||||
|
||||
*Last updated: January 2025 | Version 1.0*
|
||||
|
|
@ -133,6 +133,7 @@ Context full → /compact or /clear
|
|||
- [9.7 Output Styles](#97-output-styles)
|
||||
- [9.8 Vibe Coding & Skeleton Projects](#98-vibe-coding--skeleton-projects)
|
||||
- [9.9 Batch Operations Pattern](#99-batch-operations-pattern)
|
||||
- [9.10 Continuous Improvement Mindset](#910-continuous-improvement-mindset)
|
||||
- [10. Reference](#10-reference)
|
||||
- [10.1 Commands Table](#101-commands-table)
|
||||
- [10.2 Keyboard Shortcuts](#102-keyboard-shortcuts)
|
||||
|
|
@ -859,6 +860,40 @@ Personal overrides not committed to git (add to .gitignore):
|
|||
| Update when conventions change | Let it go stale |
|
||||
| Reference external docs | Duplicate documentation |
|
||||
|
||||
### Single Source of Truth Pattern
|
||||
|
||||
When using multiple AI tools (Claude Code, CodeRabbit, SonarQube, Copilot...), they can conflict if each has different conventions. The solution: **one source of truth for all tools**.
|
||||
|
||||
**Recommended structure**:
|
||||
|
||||
```
|
||||
/docs/conventions/
|
||||
├── coding-standards.md # Style, naming, patterns
|
||||
├── architecture.md # System design decisions
|
||||
├── testing.md # Test conventions
|
||||
└── anti-patterns.md # What to avoid
|
||||
```
|
||||
|
||||
**Then reference from everywhere**:
|
||||
|
||||
```markdown
|
||||
# In CLAUDE.md
|
||||
@docs/conventions/coding-standards.md
|
||||
@docs/conventions/architecture.md
|
||||
```
|
||||
|
||||
```yaml
|
||||
# In .coderabbit.yml
|
||||
knowledge_base:
|
||||
code_guidelines:
|
||||
filePatterns:
|
||||
- "docs/conventions/*.md"
|
||||
```
|
||||
|
||||
**Why this matters**: Without a single source, your local agent might approve code that CodeRabbit then flags — wasting cycles. With aligned conventions, all tools enforce the same standards.
|
||||
|
||||
> Inspired by [Nick Tune's Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa)
|
||||
|
||||
## 3.2 The .claude/ Folder Structure
|
||||
|
||||
The `.claude/` folder is your project's Claude Code directory for memory, settings, and extensions.
|
||||
|
|
@ -2437,6 +2472,34 @@ Hooks are scripts that run automatically when specific events occur.
|
|||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Shell Scripts vs AI Agents: When to Use What
|
||||
|
||||
Not everything needs AI. Choose the right tool:
|
||||
|
||||
| Task Type | Best Tool | Why | Example |
|
||||
|-----------|-----------|-----|---------|
|
||||
| **Deterministic** | Bash script | Fast, predictable, no tokens | Create branch, fetch PR comments |
|
||||
| **Pattern-based** | Bash + regex | Reliable for known patterns | Check for secrets, validate format |
|
||||
| **Interpretation needed** | AI Agent | Judgment required | Code review, architecture decisions |
|
||||
| **Context-dependent** | AI Agent | Needs understanding | "Does this match requirements?" |
|
||||
|
||||
**Rule of thumb**: If you can write a regex or a simple conditional for it, use a bash script. If it requires "understanding" or "judgment", use an agent.
|
||||
|
||||
**Example — PR workflow**:
|
||||
```bash
|
||||
# Deterministic (bash): create branch, push, open PR
|
||||
git checkout -b feature/xyz
|
||||
git push -u origin feature/xyz
|
||||
gh pr create --title "..." --body "..."
|
||||
|
||||
# Interpretation (agent): review code quality
|
||||
# → Use code-review subagent
|
||||
```
|
||||
|
||||
**Why this matters**: Bash scripts are instant, free (no tokens), and 100% predictable. Reserve AI for tasks that genuinely need intelligence.
|
||||
|
||||
> Inspired by [Nick Tune's Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa)
|
||||
|
||||
## 7.2 Creating Hooks
|
||||
|
||||
### Hook Registration (settings.json)
|
||||
|
|
@ -3267,6 +3330,100 @@ jobs:
|
|||
Output as markdown."
|
||||
```
|
||||
|
||||
### Verify Gate Pattern
|
||||
|
||||
Before creating a PR, ensure all local checks pass. This prevents wasted CI cycles and review time.
|
||||
|
||||
**The pattern**:
|
||||
|
||||
```
|
||||
Build ✓ → Lint ✓ → Test ✓ → Type-check ✓ → THEN create PR
|
||||
```
|
||||
|
||||
**Implementation as a command** (`.claude/commands/complete-task.md`):
|
||||
|
||||
```markdown
|
||||
# Complete Task
|
||||
|
||||
Run the full verification gate before creating a PR:
|
||||
|
||||
1. **Build**: Run `pnpm build` - must succeed
|
||||
2. **Lint**: Run `pnpm lint` - must have zero errors
|
||||
3. **Test**: Run `pnpm test` - all tests must pass
|
||||
4. **Type-check**: Run `pnpm typecheck` - no type errors
|
||||
|
||||
If ANY step fails:
|
||||
- Stop immediately
|
||||
- Report what failed and why
|
||||
- Suggest fixes
|
||||
- Do NOT proceed to PR creation
|
||||
|
||||
If ALL steps pass:
|
||||
- Create the PR with `gh pr create`
|
||||
- Wait for CI with `gh pr checks --watch`
|
||||
- If CI fails, fetch feedback and auto-fix
|
||||
- Loop until mergeable or blocked
|
||||
```
|
||||
|
||||
**Autonomous retry loop**:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ VERIFY GATE + AUTO-FIX │
|
||||
├─────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Local checks (build/lint/test) │
|
||||
│ │ │
|
||||
│ ▼ FAIL? │
|
||||
│ ┌─────────┐ │
|
||||
│ │ Auto-fix│ ──► Re-run checks │
|
||||
│ └─────────┘ │
|
||||
│ │ │
|
||||
│ ▼ PASS │
|
||||
│ Create PR │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Wait for CI (gh pr checks --watch) │
|
||||
│ │ │
|
||||
│ ▼ FAIL? │
|
||||
│ ┌─────────────────────┐ │
|
||||
│ │ Fetch CI feedback │ │
|
||||
│ │ (CodeRabbit, etc.) │ │
|
||||
│ └─────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Auto-fix + push + loop │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ PR mergeable OR blocked (ask human) │
|
||||
│ │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Fetching CI feedback** (GitHub GraphQL):
|
||||
|
||||
```bash
|
||||
# Get PR review status and comments
|
||||
gh api graphql -f query='
|
||||
query($pr: Int!) {
|
||||
repository(owner: "OWNER", name: "REPO") {
|
||||
pullRequest(number: $pr) {
|
||||
reviewDecision
|
||||
reviewThreads(first: 100) {
|
||||
nodes {
|
||||
isResolved
|
||||
comments(first: 1) {
|
||||
nodes { body }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}' -F pr=$PR_NUMBER
|
||||
```
|
||||
|
||||
> Inspired by [Nick Tune's Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa)
|
||||
|
||||
## 9.4 IDE Integration
|
||||
|
||||
### VS Code Integration
|
||||
|
|
@ -3714,6 +3871,59 @@ User: Add error boundaries to all page components:
|
|||
List affected files first, then make changes."
|
||||
```
|
||||
|
||||
## 9.10 Continuous Improvement Mindset
|
||||
|
||||
The goal isn't just to use AI for coding — it's to **continuously improve the workflow** so AI produces better results with less intervention.
|
||||
|
||||
### The Key Question
|
||||
|
||||
After every manual intervention, ask yourself:
|
||||
|
||||
> "How can I improve the process so this error or manual fix can be avoided next time?"
|
||||
|
||||
### Improvement Pipeline
|
||||
|
||||
```
|
||||
Error or manual intervention detected
|
||||
│
|
||||
▼
|
||||
Can a linting rule catch it?
|
||||
│
|
||||
YES ─┴─ NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Add lint Can it go in conventions/docs?
|
||||
rule │
|
||||
YES ─┴─ NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Add to Accept as
|
||||
CLAUDE.md edge case
|
||||
or ADRs
|
||||
```
|
||||
|
||||
### Practical Examples
|
||||
|
||||
| Problem | Solution | Where to Add |
|
||||
|---------|----------|--------------|
|
||||
| Agent forgets to run tests | Add to workflow command | `.claude/commands/complete-task.md` |
|
||||
| Code review catches style issue | Add ESLint rule | `.eslintrc.js` |
|
||||
| Same architecture mistake repeated | Document decision | `docs/conventions/architecture.md` |
|
||||
| Agent uses wrong import pattern | Add example | `CLAUDE.md` |
|
||||
|
||||
### The Mindset Shift
|
||||
|
||||
Traditional: *"I write code, AI helps"*
|
||||
|
||||
AI-native: *"I improve the workflow and context so AI writes better code"*
|
||||
|
||||
> "Software engineering might be more workflow + context engineering."
|
||||
> — Nick Tune
|
||||
|
||||
This is the meta-skill: instead of fixing code, **fix the system that produces the code**.
|
||||
|
||||
> Inspired by [Nick Tune's Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa)
|
||||
|
||||
---
|
||||
|
||||
# 10. Reference
|
||||
|
|
@ -4418,6 +4628,112 @@ exit 0
|
|||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
### Nick Tune: Coding Agent Development Workflows
|
||||
|
||||
**Article**: [Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa) by Nick Tune
|
||||
|
||||
Nick Tune's article explores a more **autonomous, pipeline-driven approach** to AI-assisted development. His workflow aims for fully autonomous task completion: the agent starts from a ticket and delivers a mergeable PR with minimal human intervention.
|
||||
|
||||
**Key concepts from his approach**:
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| **Task Completion Pipeline** | Orchestrated flow: local checks → code review → PR → CI → auto-fix → loop until mergeable |
|
||||
| **Single Source of Truth** | All conventions in `/docs/`, referenced by every tool (Claude, CodeRabbit, SonarQube) |
|
||||
| **Shell vs AI Decision** | Deterministic tasks = bash scripts; interpretation needed = AI agents |
|
||||
| **Verify Gate** | Build/lint/test must pass locally BEFORE PR creation |
|
||||
| **Continuous Improvement** | Every manual intervention = opportunity to improve the workflow |
|
||||
|
||||
**His approach vs this guide**:
|
||||
|
||||
| Aspect | This Guide | Nick Tune's Approach |
|
||||
|--------|------------|---------------------|
|
||||
| **Focus** | Learning Claude Code comprehensively | Optimizing autonomous workflows |
|
||||
| **Audience** | Beginners to advanced | Advanced practitioners |
|
||||
| **Philosophy** | Master the tool, then customize | Automate aggressively from day one |
|
||||
| **Workflow** | Interactive, human-in-the-loop | Autonomous, human-at-the-end |
|
||||
| **Tooling** | Claude Code-centric | Multi-tool orchestration (CodeRabbit, SonarQube, GitHub GraphQL) |
|
||||
|
||||
**When to adopt his patterns**:
|
||||
|
||||
- You're comfortable with Claude Code basics
|
||||
- You want near-autonomous PR generation
|
||||
- You have CI/CD infrastructure (GitHub Actions, CodeRabbit, etc.)
|
||||
- You're working on a project where you can invest in workflow setup
|
||||
|
||||
**Recommended reading order**:
|
||||
1. This guide (master fundamentals)
|
||||
2. Nick Tune's article (advanced automation)
|
||||
|
||||
### Community Resources
|
||||
|
||||
The Claude Code ecosystem is growing rapidly. Here are curated resources to continue learning:
|
||||
|
||||
#### Awesome Lists
|
||||
|
||||
| Repository | Focus | Last Updated |
|
||||
|------------|-------|--------------|
|
||||
| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | Commands, workflows, IDE integrations | Apr 2025 |
|
||||
| [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) | Custom skills collection | Oct 2025 |
|
||||
| [awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | Full-stack & DevOps subagents | Jul 2025 |
|
||||
| [awesome-claude](https://github.com/alvinunreal/awesome-claude) | General Claude resources (SDKs, tools) | Aug 2025 |
|
||||
| [awesome-claude-prompts](https://github.com/langgptai/awesome-claude-prompts) | Prompt templates for various use cases | 2023 |
|
||||
|
||||
#### Frameworks
|
||||
|
||||
| Framework | Description | Link |
|
||||
|-----------|-------------|------|
|
||||
| **SuperClaude** | Advanced configuration framework with 30+ commands (`/sc:*`), cognitive personas, and MCP integration | [GitHub](https://github.com/SuperClaude-Org/SuperClaude_Framework) |
|
||||
|
||||
SuperClaude transforms Claude Code into a structured development platform through behavioral instruction injection. Key features:
|
||||
- 30+ specialized commands for common dev tasks
|
||||
- Smart personas for different contexts
|
||||
- MCP server integration
|
||||
- Task management and session persistence
|
||||
|
||||
#### Learning Sites
|
||||
|
||||
| Site | Description |
|
||||
|------|-------------|
|
||||
| [Claudelog.com](https://claudelog.com/) | Tips, patterns, tutorials, and best practices |
|
||||
| [Official Docs](https://docs.anthropic.com/en/docs/claude-code) | Anthropic's official Claude Code documentation |
|
||||
|
||||
> **Tip**: These resources evolve quickly. Star repos you find useful to track updates.
|
||||
|
||||
### Tools
|
||||
|
||||
#### Audit Your Setup
|
||||
|
||||
Use the included audit prompt to analyze your current Claude Code configuration:
|
||||
|
||||
**File**: [`claude-setup-audit-prompt.md`](./claude-setup-audit-prompt.md)
|
||||
|
||||
**What it does**:
|
||||
1. Scans your global (`~/.claude/`) and project (`.claude/`) configuration
|
||||
2. Compares against best practices from this guide
|
||||
3. Generates a prioritized report with actionable recommendations
|
||||
4. Provides ready-to-use templates tailored to your tech stack
|
||||
|
||||
**How to use**:
|
||||
1. Copy the prompt from the file
|
||||
2. Run `claude --ultrathink` in your project directory
|
||||
3. Paste the prompt and review findings
|
||||
4. Choose which recommendations to implement
|
||||
|
||||
**Example output**:
|
||||
|
||||
| Priority | Element | Status | Action |
|
||||
|----------|---------|--------|--------|
|
||||
| 🔴 High | Project CLAUDE.md | ❌ | Create with tech stack + conventions |
|
||||
| 🟡 Medium | Security hooks | ⚠️ | Add PreToolUse for secrets check |
|
||||
| 🟢 Low | MCP Serena | ❌ | Configure for large codebase |
|
||||
|
||||
The audit covers: Memory files, folder structure, agents, hooks, MCP servers, context management, and CI/CD integration patterns.
|
||||
|
||||
---
|
||||
|
||||
## About This Guide
|
||||
|
||||
**End of Guide**
|
||||
|
|
@ -4428,7 +4744,9 @@ exit 0
|
|||
|
||||
**Written with**: Claude (Anthropic) - This guide was collaboratively written with Claude Code, demonstrating the tool's capabilities for technical documentation.
|
||||
|
||||
**Inspired by**: [Claudelog.com](https://claudelog.com/) - An excellent resource for Claude Code tips, patterns, and advanced techniques that served as a major reference for this guide.
|
||||
**Inspired by**:
|
||||
- [Claudelog.com](https://claudelog.com/) - An excellent resource for Claude Code tips, patterns, and advanced techniques that served as a major reference for this guide.
|
||||
- [Nick Tune's Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa) - Advanced workflow patterns integrated in sections 3.1, 7.1, 9.3, and 9.10.
|
||||
|
||||
**License**: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) - Feel free to use, adapt, and share with attribution.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue