docs: integrate Gur Sannikov ADR workflow + native capabilities audit (4/5)
- Add ADR-Driven Development pattern to methodologies.md (~60 lines) - Pattern: ADR → skill → native execution - Example ADR template (database migration) - Complete bash workflow with benefits - Add Native Capabilities Audit checklist to architecture.md (~50 lines) - 11 native capabilities with internal links - Onboarding tip for comprehension audit - Add Dynamic Model Switching pattern to cheatsheet.md (~40 lines) - Pattern: Sonnet → Opus → Sonnet - Cost comparison table and best practices - Add Community Validation to architecture.md (~15 lines) - External validation of 'less scaffolding, more model' approach - Cursor power user adopting Agent Skills standard - Track evaluation in docs/resource-evaluations/ (full methodology) - Update evaluations count: 24 → 55 (README + reference.yaml) - Update CHANGELOG.md with integration details Source: https://www.linkedin.com/posts/gursannikov_claudecode-embeddedengineering-aiagents-activity-7423851983331328001-DrFb Score: 4/5 (HIGH VALUE) - fills ADR workflow gap + onboarding checklist Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
b48d95c024
commit
4c0e4b6ac6
7 changed files with 389 additions and 6 deletions
|
|
@ -154,6 +154,60 @@ The model itself decides when to call tools, which tools to call, and when it's
|
|||
3. **Flexibility**: No rigid pipeline constraining what Claude can do
|
||||
4. **Debuggability**: Easy to understand what happened and why
|
||||
|
||||
### Native Capabilities Audit
|
||||
|
||||
Use this checklist to verify you understand Claude Code's full surface area. Each capability is documented in detail elsewhere in this guide.
|
||||
|
||||
**The 11 Native Capabilities**:
|
||||
|
||||
- [ ] **Event Hooks** — Bash/PowerShell scripts triggered on tool execution
|
||||
- PreToolUse, PostToolUse, UserPromptSubmit, Notification
|
||||
- See: [Section 5 Hooks](#5-permission--security-model)
|
||||
|
||||
- [ ] **Skill-Scoped Hooks** — Event hooks specific to skill execution context
|
||||
- Lifecycle management per skill
|
||||
- See: [Ultimate Guide Section 5.11](./ultimate-guide.md#511-skills)
|
||||
|
||||
- [ ] **Background Agents** — Async task execution (test suites, long operations)
|
||||
- Non-blocking agent spawning
|
||||
- See: [Section 4.2 Sub-Agent Architecture](#4-sub-agent-architecture)
|
||||
|
||||
- [ ] **Explore Subagent** — `/explore` for codebase analysis
|
||||
- Read-only codebase exploration
|
||||
- See: [Section 4.2 Sub-Agents](#4-sub-agent-architecture)
|
||||
|
||||
- [ ] **Plan Subagent** — `/plan` for read-only planning mode
|
||||
- Safe architectural exploration
|
||||
- See: [Ultimate Guide Section 2.3](./ultimate-guide.md#23-plan-mode)
|
||||
|
||||
- [ ] **Task Tool** — Hierarchical task delegation to specialized agents
|
||||
- Parallel task execution, depth=1 sub-agents
|
||||
- See: [Section 4.2 Sub-Agent Architecture](#4-sub-agent-architecture)
|
||||
|
||||
- [ ] **Agent Teams** — Multi-agent parallel coordination (experimental v2.1.32+)
|
||||
- Git-based coordination, autonomous task claiming
|
||||
- See: [Ultimate Guide Section 9.20](./ultimate-guide.md#920-agent-teams)
|
||||
|
||||
- [ ] **Per-Task Model Selection** — Dynamic model switching mid-session
|
||||
- `/model opus|sonnet|haiku` on task boundaries
|
||||
- See: [Section 10 Cost Optimization](#10-claude-code-vs-alternatives)
|
||||
|
||||
- [ ] **MCP Protocol Integration** — Model Context Protocol for tool extensions
|
||||
- Context7, Sequential, Serena, Playwright, etc.
|
||||
- See: [Section 6 MCP Integration](#6-mcp-integration)
|
||||
|
||||
- [ ] **Permission Modes** — Fine-grained control over tool execution
|
||||
- Default, auto-accept, plan mode, custom rules
|
||||
- See: [Section 5 Permission & Security Model](#5-permission--security-model)
|
||||
|
||||
- [ ] **Session Memory** — Persistent context across sessions
|
||||
- CLAUDE.md, memory files, project state
|
||||
- See: [Section 8 Session Persistence](#8-session-persistence)
|
||||
|
||||
**Onboarding Tip**: If you haven't explored all 11 capabilities, you're likely missing productivity opportunities. Focus on the unchecked items above.
|
||||
|
||||
**Source**: Synthesized from [Gur Sannikov analysis](https://www.linkedin.com/posts/gursannikov_claudecode-embeddedengineering-aiagents-activity-7423851983331328001-DrFb)
|
||||
|
||||
---
|
||||
|
||||
## 2. The Tool Arsenal
|
||||
|
|
@ -1156,6 +1210,14 @@ The core philosophy behind Claude Code:
|
|||
| Fewer bugs | Model errors affect everything |
|
||||
| Fast iteration | Requires good model quality |
|
||||
|
||||
### Community Validation
|
||||
|
||||
The "native capabilities first" approach is increasingly validated by external practitioners. Embedded engineering teams (including former Cursor power users) converge on Agent Skills standard over external orchestration frameworks, demonstrating the viability of trusting Claude's native reasoning over adding scaffolding layers.
|
||||
|
||||
**Example**: [Gur Sannikov](https://www.linkedin.com/posts/gursannikov_claudecode-embeddedengineering-aiagents-activity-7423851983331328001-DrFb) (embedded engineering) adopted ADR-driven workflows using only native Claude Code capabilities (hooks, skills, Task Tool) without external frameworks — validating the architectural philosophy documented in this guide.
|
||||
|
||||
This convergence suggests that the "less scaffolding, more model" approach scales beyond initial expectations, even for complex engineering domains like embedded systems development.
|
||||
|
||||
---
|
||||
|
||||
## 10. Claude Code vs Alternatives
|
||||
|
|
|
|||
|
|
@ -215,6 +215,41 @@ Model: Sonnet | Ctx: 89.5k | Cost: $2.11 | Ctx(u): 56.0%
|
|||
|
||||
**Required for**: features >3 files, architecture, complex debugging
|
||||
|
||||
### Dynamic Model Switching (Mid-Session)
|
||||
|
||||
**Pattern**: Start Sonnet (speed) → swap Opus (complexity) → back Sonnet
|
||||
|
||||
**Workflow**:
|
||||
```bash
|
||||
# Session start (default Sonnet)
|
||||
claude
|
||||
|
||||
# Complex feature encountered
|
||||
> "Implement OAuth2 flow with PKCE"
|
||||
/model opus # Switch to deep reasoning
|
||||
|
||||
# Feature complete, back to routine
|
||||
/model sonnet # Speed + cost optimization
|
||||
```
|
||||
|
||||
**Best Practices**:
|
||||
- ✅ Swap **on task boundaries**, not mid-task
|
||||
- ✅ Use Opus for: architecture decisions, complex debugging, security-critical code
|
||||
- ✅ Use Sonnet for: routine edits, refactoring, test writing
|
||||
- ✅ Use Haiku for: simple fixes, typos, validation checks
|
||||
- ❌ Don't swap mid-implementation (context loss)
|
||||
|
||||
**Cost Impact**:
|
||||
| Model | Input | Output | Use Case |
|
||||
|-------|--------|--------|----------|
|
||||
| Opus | $15/MTok | $75/MTok | Complex reasoning (10-20% of tasks) |
|
||||
| Sonnet | $3/MTok | $15/MTok | Most development (70-80% of tasks) |
|
||||
| Haiku | $0.25/MTok | $1.25/MTok | Simple validation (5-10% of tasks) |
|
||||
|
||||
**Dynamic switching** optimizes cost while maintaining quality on complex tasks.
|
||||
|
||||
**Source**: [Gur Sannikov embedded engineering workflow](https://www.linkedin.com/posts/gursannikov_claudecode-embeddedengineering-aiagents-activity-7423851983331328001-DrFb)
|
||||
|
||||
---
|
||||
|
||||
## MCP Servers
|
||||
|
|
|
|||
|
|
@ -272,6 +272,56 @@ Meta-Agent (Orchestrator)
|
|||
└── Reviewer (validation)
|
||||
```
|
||||
|
||||
### ADR-Driven Development
|
||||
|
||||
**Pattern**: Write plain English ADRs → Feed to implement-adr skill → Execute natively
|
||||
|
||||
Architecture Decision Records (ADRs) combined with Claude Code skills create a workflow where architectural decisions drive implementation directly.
|
||||
|
||||
**Workflow Steps**:
|
||||
1. **Document decision** in ADR format (context, decision, consequences)
|
||||
2. **Create implementation skill** (generic or `implement-adr` specialized)
|
||||
3. **Feed ADR as prompt** to skill with clear acceptance criteria
|
||||
4. **Claude executes** based on architectural guidance in ADR
|
||||
|
||||
**Example ADR Template**:
|
||||
```
|
||||
# ADR-001: Database Migration Strategy
|
||||
|
||||
## Context
|
||||
Legacy MySQL schema needs migration to PostgreSQL for better JSON support.
|
||||
|
||||
## Decision
|
||||
Use incremental dual-write pattern with feature flags.
|
||||
|
||||
## Consequences
|
||||
- Positive: Zero-downtime migration
|
||||
- Negative: Temporary code complexity during transition
|
||||
```
|
||||
|
||||
**Implementation Workflow**:
|
||||
```bash
|
||||
# 1. Write ADR (plain English)
|
||||
vim docs/adr/001-database-migration.md
|
||||
|
||||
# 2. Feed to implementation skill
|
||||
/implement-adr docs/adr/001-database-migration.md
|
||||
|
||||
# 3. Claude executes based on ADR guidance
|
||||
# → Creates migration scripts
|
||||
# → Updates ORM configuration
|
||||
# → Adds feature flags
|
||||
# → Implements dual-write logic
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ **Documentation-driven**: Architecture and code stay synchronized
|
||||
- ✅ **Native execution**: No external frameworks needed
|
||||
- ✅ **Traceable decisions**: Clear audit trail from decision to implementation
|
||||
- ✅ **Team alignment**: ADRs communicate intent to both humans and AI
|
||||
|
||||
**Source**: [Gur Sannikov embedded engineering workflow](https://www.linkedin.com/posts/gursannikov_claudecode-embeddedengineering-aiagents-activity-7423851983331328001-DrFb)
|
||||
|
||||
---
|
||||
|
||||
### Tier 6: Optimization
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue