diff --git a/README.md b/README.md index a1e788b..403dec1 100644 --- a/README.md +++ b/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 --- diff --git a/claude-setup-audit-prompt.md b/claude-setup-audit-prompt.md new file mode 100644 index 0000000..4fef718 --- /dev/null +++ b/claude-setup-audit-prompt.md @@ -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* diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md index bf65c12..1f022a3 100644 --- a/english-ultimate-claude-code-guide.md +++ b/english-ultimate-claude-code-guide.md @@ -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.