diff --git a/CHANGELOG.md b/CHANGELOG.md index fcfee20..542431c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,6 +64,49 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Hook events (TeammateIdle, TaskCompleted) - Agent memory field, Xcode integration, adaptive thinking - Updated: 2026-02-09 +- **llms.txt Standard Documentation** (Section 9.18.4): AI-optimized documentation indexing + - **Concept explanation**: llms.txt as documentation discovery standard for LLMs + - **Format and structure**: Plain text index at `/llms.txt` or `/machine-readable/llms.txt` + - **Complementarity with MCP**: Clarifies llms.txt (static index) vs Context7 MCP (runtime lookup) + - **Implementation examples**: Minimal and advanced patterns with line numbers + - **CLAUDE.md integration**: How llms.txt and CLAUDE.md serve different purposes + - **Repository example**: References this guide's own `machine-readable/llms.txt` implementation + - Section: Documentation Formats for Agents (line 14544) + - Resource: docs/resource-evaluations/wasp-fullstack-essentials-eval.md (score 3/5) + - Source: llmstxt.org specification (official standard) + - Gap addressed: Repository had llms.txt file without conceptual documentation +- **Background Tasks Workflow** (Section 9.5): Fullstack development patterns with Ctrl+B + - **When to background**: 5 scenarios (dev server, test watcher, build, migration, docker) + - **Fullstack workflow pattern**: Dev server backgrounded while iterating on frontend + - **Real-world example**: API + frontend iteration maintaining tight feedback loops + - **Context rot prevention**: `/tasks` monitoring strategies + - **Limitations**: No foreground command, session-scoped tasks, output visibility + - **Teleportation integration**: Background tasks not transferred, restart required + - **Disable flag**: `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable (v2.1.4+) + - Section: Background Tasks for Fullstack Development (line 11057) + - Resource: docs/resource-evaluations/wasp-fullstack-essentials-eval.md (score 3/5) + - Gap addressed: Ctrl+B documented as feature, now complete workflow strategy +- **Chrome DevTools MCP Server** (mcp-servers-ecosystem.md): Debugging and inspection capabilities + - **Official Anthropic server**: Chrome DevTools Protocol integration + - **Use case**: Debugging web apps, runtime inspection, complements Playwright MCP + - **Key features**: Console access, network monitoring, DOM inspection, JS execution, profiling + - **Comparison table**: Chrome DevTools (debugging) vs Playwright (testing) + - **Setup and limitations**: Manual Chrome launch with remote debugging port + - Section: Browser Automation (line 418) + - Statistics: 3 browser servers (was 2), 6 official servers (was 5) + - Resource: docs/resource-evaluations/wasp-fullstack-essentials-eval.md (score 3/5) + - npm: @modelcontextprotocol/server-chrome-devtools +- **Convention-Over-Configuration for AI** (Section 9.18.1): Framework selection impact + - **Problem**: Custom architectures require extensive CLAUDE.md documentation + - **Solution**: Opinionated frameworks reduce agent cognitive load through conventions + - **Comparison table**: Custom vs opinionated architectures (file organization, routing, testing) + - **Framework examples**: Next.js, Rails, Phoenix, Django with convention benefits + - **Real-world impact**: Fewer mistakes, faster boilerplate, smaller CLAUDE.md files + - **Trade-offs**: Faster onboarding vs architectural flexibility + - **CLAUDE.md connection**: Convention-over-config directly reduces token requirements + - Section: Convention-Over-Configuration for AI Agents (line 14380) + - Resource: docs/resource-evaluations/wasp-fullstack-essentials-eval.md (score 3/5) + - Gap addressed: Existing AX framework concept reinforced with framework angle ### Changed diff --git a/README.md b/README.md index 65db4dc..0a968ff 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

Stars Quiz - Templates + Templates

@@ -15,7 +15,7 @@ Ask Zread

-> **Claude Code (Anthropic): the learning curve, solved.** ~16K-line guide + 107 templates + 257 quiz questions + 22 event hooks + 55 resource evaluations. Beginner ā†’ Power User. +> **Claude Code (Anthropic): the learning curve, solved.** ~19K-line guide + 111 templates + 257 quiz questions + 22 event hooks + 56 resource evaluations. Beginner ā†’ Power User. --- @@ -66,12 +66,12 @@ Save as `CLAUDE.md` in your project root. Claude reads it automatically. graph LR root[šŸ“¦ Repository
Root] - root --> guide[šŸ“– guide/
16K lines] - root --> examples[šŸ“‹ examples/
106 templates] + root --> guide[šŸ“– guide/
19K lines] + root --> examples[šŸ“‹ examples/
111 templates] root --> quiz[šŸ§  quiz/
257 questions] root --> tools[šŸ”§ tools/
utils] root --> machine[šŸ¤– machine-readable/
AI index] - root --> docs[šŸ“š docs/
55 evaluations] + root --> docs[šŸ“š docs/
56 evaluations] style root fill:#d35400,stroke:#e67e22,stroke-width:3px,color:#fff style guide fill:#2980b9,stroke:#3498db,stroke-width:2px,color:#fff @@ -88,7 +88,7 @@ graph LR ``` šŸ“¦ claude-code-ultimate-guide/ ā”‚ -ā”œā”€ šŸ“– guide/ Core Documentation (~16K lines) +ā”œā”€ šŸ“– guide/ Core Documentation (~19K lines) ā”‚ ā”œā”€ ultimate-guide.md Complete reference, 10 sections ā”‚ ā”œā”€ cheatsheet.md 1-page printable ā”‚ ā”œā”€ architecture.md How Claude Code works internally @@ -96,7 +96,7 @@ graph LR ā”‚ ā”œā”€ mcp-servers-ecosystem.md Official & community MCP servers ā”‚ ā””ā”€ workflows/ Step-by-step guides ā”‚ -ā”œā”€ šŸ“‹ examples/ 107 Production Templates +ā”œā”€ šŸ“‹ examples/ 111 Production Templates ā”‚ ā”œā”€ agents/ 6 custom AI personas ā”‚ ā”œā”€ commands/ 18 slash commands ā”‚ ā”œā”€ hooks/ 18 security hooks (bash + PowerShell) @@ -383,7 +383,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv | File | Purpose | Time | |------|---------|------| -| **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (~16K lines), 10 sections | ~4 hours | +| **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (~19K lines), 10 sections | ~4 hours | | **[Cheat Sheet](./guide/cheatsheet.md)** | 1-page printable reference | 5 min | | **[Visual Reference](./guide/visual-reference.md)** | 20 ASCII diagrams for key concepts | 5 min | | **[Architecture](./guide/architecture.md)** | How Claude Code works internally | 25 min | @@ -401,7 +401,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv | **[Claude Code Releases](./guide/claude-code-releases.md)** | Official release history | 10 min |
-Examples Library (106 templates) +Examples Library (111 templates) **Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ā­ diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 5787f78..adc2d6c 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -3769,15 +3769,15 @@ impact (High/Medium/Low) without considering security or maintainability trade-offs. ``` -**When to split roles:** -- Code reviews requiring 3+ distinct expertise areas -- Architecture decisions with competing concerns (performance vs. security vs. DX) -- Migration planning where different stakeholders have different priorities +**When to use scope-focused agents:** +- Analysis requiring 3+ distinct context boundaries (security scope, perf scope, API scope) +- Competing concerns that benefit from isolated evaluation (performance vs. security vs. DX) +- Large codebases where full context would pollute analysis of specific aspects -**When NOT to split:** -- Simple reviews (one agent covers all aspects) +**When NOT to use scope-focused agents:** +- Simple reviews (one agent with full context covers all aspects) - Time-constrained situations (overhead of synthesis outweighs benefit) -- Tasks where perspectives aren't genuinely distinct +- Tasks where scopes aren't genuinely independent (overlapping context needed) ### The Philosophy diff --git a/guide/workflows/agent-teams-quick-start.md b/guide/workflows/agent-teams-quick-start.md index ca1ce90..d889126 100644 --- a/guide/workflows/agent-teams-quick-start.md +++ b/guide/workflows/agent-teams-quick-start.md @@ -206,20 +206,23 @@ Team: doc-update (3 agents) **Copy-paste prompt**: ``` > Update documentation for new "[FEATURE NAME]" feature: -> - Content writer: Write section [X.Y] in guide/ultimate-guide.md with: +> - Content Scope: Write section [X.Y] in guide/ultimate-guide.md with: > - Overview (what/why/when) > - 2-3 concrete examples > - Best practices + gotchas > - Links to related sections -> - Index updater: Update: +> Context: guide/ultimate-guide.md section [X.Y] only +> - Index Scope: Update: > - guide/ultimate-guide.md TOC (add section [X.Y]) > - machine-readable/reference.yaml (add entry with line numbers) > - README.md navigation (add link if major feature) -> - Consistency checker: Verify: +> Context: Index files only (TOC, reference.yaml, README.md) +> - Consistency Scope: Verify: > - All cross-references resolve correctly > - Line numbers in reference.yaml match actual content > - Anchors in README point to correct sections > - No broken internal links +> Context: All modified files for cross-reference validation ``` **ROI**: @@ -259,22 +262,25 @@ Team: security-pr-review (3 agents) **Copy-paste prompt**: ``` -> Review PR #[NUMBER] with security focus: -> - Rust expert: Check: +> Review PR #[NUMBER] with scope-focused analysis: +> - Rust Scope: Check: > - Ownership patterns (prefer &str over String, minimize clones) > - Error handling (anyhow::Result with .context(), no unwrap outside tests) > - Idiomatic code (impl after type, #[cfg(test)] mod tests) > - Clippy compliance (zero warnings) -> - Security auditor: Scan for: +> Context: All modified .rs files +> - Security Scope: Scan for: > - Command injection (shell escapes, argument sanitization) > - Token/credential leaks (hardcoded secrets, logs, error messages) > - Input sanitization (path traversal, regex DoS) > - File operations (path validation, permissions) -> - Perf analyzer: Review: +> Context: Input handling, auth, file I/O code +> - Performance Scope: Review: > - Unnecessary allocations (String::from vs &str) > - Async patterns (spawn_blocking for CPU-bound work) > - Compiled regex (lazy_static! for hot paths) > - Algorithm complexity (O(n) vs O(nĀ²)) +> Context: Hot paths, loops, async functions ``` **ROI**: @@ -326,7 +332,7 @@ Verdict: āœ… Critical security issues caught, PR requires revision **Use Agent Teams when**: - āœ… You'd naturally think "I should check X, Y, and Z" - āœ… High stakes (production release, external contributor, security-sensitive) -- āœ… Multi-domain expertise needed (Rust + Security + Performance) +- āœ… Multi-scope analysis needed (Rust scope + Security scope + Performance scope) - āœ… Cross-file consistency matters (links, counts, versions sync) - āœ… Parallel work possible (independent tasks, no sequential dependency) @@ -351,11 +357,11 @@ claude # 3. Create team (prompt template) > Create a team to [TASK]: -> - Agent 1 ([ROLE]): [SPECIFIC MISSION] -> - Agent 2 ([ROLE]): [SPECIFIC MISSION] -> - Agent 3 ([ROLE]): [SPECIFIC MISSION] +> - Agent 1 ([SCOPE/CONTEXT]): [SPECIFIC MISSION] +> - Agent 2 ([SCOPE/CONTEXT]): [SPECIFIC MISSION] +> - Agent 3 ([SCOPE/CONTEXT]): [SPECIFIC MISSION] > -> [CONTEXT/FILES TO REVIEW] +> [FILES/DIRECTORIES TO ANALYZE] # 4. Observe (optional) # Shift+Up/Down to see individual agent outputs @@ -381,19 +387,19 @@ claude #### Security PR Review (RTK) ``` -> Review PR #42 with security focus: -> - Rust expert: Check ownership patterns, error handling (anyhow/thiserror), idiomatic code in modified files -> - Security auditor: Scan for injection risks, token leaks, input sanitization -> - Perf analyzer: Review allocations, async patterns, compiled regex +> Review PR #42 with scope-focused analysis: +> - Rust Scope: Check ownership patterns, error handling (anyhow/thiserror), idiomatic code in modified files (context: src/**/*.rs) +> - Security Scope: Scan for injection risks, token leaks, input sanitization (context: auth, input handling code) +> - Performance Scope: Review allocations, async patterns, compiled regex (context: hot paths, loops) ``` #### Multi-File Doc Update ``` > Update documentation for new "Agent Teams Quick Start" feature: -> - Content writer: Write guide/workflows/agent-teams-quick-start.md with overview, 4 patterns, decision matrix, metrics -> - Index updater: Update guide/ultimate-guide.md (add reference section 9.20), machine-readable/reference.yaml (add entry), CHANGELOG.md (add "Added" entry) -> - Consistency checker: Verify all cross-refs work, line numbers match, no broken links +> - Content Scope: Write guide/workflows/agent-teams-quick-start.md with overview, 4 patterns, decision matrix, metrics +> - Index Scope: Update guide/ultimate-guide.md (add reference section 9.20), machine-readable/reference.yaml (add entry), CHANGELOG.md (add "Added" entry) +> - Consistency Scope: Verify all cross-refs work, line numbers match, no broken links (context: all modified files) ``` #### Landing Sync Validation @@ -473,8 +479,8 @@ Verdict: āœ… High value for pre-release audits ``` **Adjust prompts** if metrics fail: -- Low convergence (<30%) ā†’ Agents too specialized, overlap prompts more -- No unique insights ā†’ Agents too similar, diversify expertise +- Low convergence (<30%) ā†’ Scopes too narrow, overlap context boundaries more +- No unique insights ā†’ Scopes too similar, diversify analysis angles - High false positives (>20%) ā†’ Prompts too vague, add concrete criteria ---