release: v3.20.3 - Competitive Analysis Gaps (claudelog.com)
9 gaps filled from claudelog.com competitive analysis (313 pages): - Section 9.19: Permutation Frameworks (CLAUDE.md-driven variation testing) - Skeleton Projects workflow (guide/workflows/skeleton-projects.md) - Task Lists as Diagnostic Tool (instruction clarity mirror) - Rev the Engine + Mechanic Stacking (multi-round planning patterns) - Split-Role Sub-Agents (multi-perspective analysis) - "You Are the Main Thread" mental model (CPU scheduler analogy) - Continuous Context Update (proactive CLAUDE.md enrichment) - Smart Hook Dispatching (single entry point routing to handlers) Guide: 15,771 → 16,293 lines (+522) New workflow: skeleton-projects.md (208 lines) Reference: +17 new entries in reference.yaml Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
950370e81b
commit
2fcc65e222
8 changed files with 812 additions and 11 deletions
|
|
@ -53,6 +53,12 @@ Improve code through multiple refinement cycles.
|
|||
|
||||
**When to use**: Quality improvements, performance optimization, code cleanup
|
||||
|
||||
### [Skeleton Projects](./skeleton-projects.md) ⭐ NEW
|
||||
|
||||
Use existing battle-tested repositories as scaffolding for new projects.
|
||||
|
||||
**When to use**: Starting new projects, standardizing team patterns, rapid prototyping from proven foundations
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Design & Content
|
||||
|
|
@ -99,6 +105,7 @@ Systematically explore and understand unfamiliar codebases.
|
|||
| **Large refactoring** | [Search Tools Mastery](./search-tools-mastery.md) |
|
||||
| **UI implementation** | [Design to Code](./design-to-code.md) |
|
||||
| **Code quality** | [Iterative Refinement](./iterative-refinement.md) |
|
||||
| **New project from template** | [Skeleton Projects](./skeleton-projects.md) |
|
||||
| **Documentation** | [PDF Generation](./pdf-generation.md) |
|
||||
| **Audio feedback** | [TTS Setup](./tts-setup.md) |
|
||||
|
||||
|
|
|
|||
208
guide/workflows/skeleton-projects.md
Normal file
208
guide/workflows/skeleton-projects.md
Normal file
|
|
@ -0,0 +1,208 @@
|
|||
# Skeleton Projects Workflow
|
||||
|
||||
Use existing, battle-tested repositories as scaffolding for new projects instead of starting from scratch.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Starting a new project** with known technology stack
|
||||
- **Standardizing team patterns** across multiple services
|
||||
- **Rapid prototyping** where architecture decisions are already made
|
||||
- **Onboarding** new team members via a working reference
|
||||
|
||||
**Don't use when**: Exploring unknown tech (use [Vibe Coding](../ultimate-guide.md#98-vibe-coding--skeleton-projects) instead), or when requirements are too unique for existing templates.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Claude Code installed and configured
|
||||
- Git access to reference repositories
|
||||
- Clear understanding of target project requirements
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Guide
|
||||
|
||||
### Phase 1: Find and Evaluate a Skeleton
|
||||
|
||||
Don't build from zero. Find an existing repo that matches your target architecture.
|
||||
|
||||
**Step 1: Search for candidates**
|
||||
|
||||
```bash
|
||||
# Ask Claude to help find reference repos
|
||||
claude -p "I need a skeleton for a Next.js 15 app with:
|
||||
- App Router
|
||||
- Prisma ORM with PostgreSQL
|
||||
- tRPC for type-safe API
|
||||
- Tailwind CSS
|
||||
- Jest + Playwright testing
|
||||
|
||||
Search GitHub for well-maintained starter templates.
|
||||
Evaluate the top 3 by: last commit date, stars, dependency freshness, test coverage."
|
||||
```
|
||||
|
||||
**Step 2: Clone and audit**
|
||||
|
||||
```bash
|
||||
git clone <candidate-repo> skeleton-eval
|
||||
cd skeleton-eval
|
||||
claude
|
||||
```
|
||||
|
||||
```markdown
|
||||
User: Audit this repository as a potential skeleton for our project:
|
||||
1. List all dependencies and their versions (flag outdated ones)
|
||||
2. Assess code quality: patterns, consistency, test coverage
|
||||
3. Identify what we'd keep vs. what we'd remove
|
||||
4. Flag any security concerns (vulnerable deps, exposed secrets)
|
||||
5. Rate overall suitability (1-5) with specific justification
|
||||
```
|
||||
|
||||
**Step 3: Evaluate with sub-agents** (for thorough analysis)
|
||||
|
||||
```markdown
|
||||
User: Run a multi-perspective evaluation of this skeleton:
|
||||
|
||||
Agent 1 (Security): Check for vulnerabilities, hardcoded secrets, unsafe patterns
|
||||
Agent 2 (Architecture): Assess modularity, separation of concerns, scalability
|
||||
Agent 3 (DX): Evaluate developer experience - setup time, documentation, tooling
|
||||
|
||||
Synthesize findings into a go/no-go recommendation.
|
||||
```
|
||||
|
||||
### Phase 2: Fork and Customize
|
||||
|
||||
**Step 4: Create your project from the skeleton**
|
||||
|
||||
```bash
|
||||
# Create new repo from skeleton
|
||||
mkdir my-project
|
||||
cp -r skeleton-eval/. my-project/
|
||||
cd my-project
|
||||
rm -rf .git
|
||||
git init
|
||||
```
|
||||
|
||||
**Step 5: Strip and adapt with Claude**
|
||||
|
||||
```markdown
|
||||
User: Customize this skeleton for our project "Acme Dashboard":
|
||||
|
||||
1. Remove: example routes, demo data, sample tests
|
||||
2. Keep: config structure, auth setup, database schema pattern, CI pipeline
|
||||
3. Update: package.json (name, description, version 0.1.0)
|
||||
4. Add: our CLAUDE.md with project conventions
|
||||
5. Verify: `pnpm install && pnpm build && pnpm test` all pass after changes
|
||||
|
||||
Important: Don't break the working skeleton. Each removal should be followed
|
||||
by a build check.
|
||||
```
|
||||
|
||||
### Phase 3: Expand from Skeleton to MVP
|
||||
|
||||
**Step 6: Build the first real feature**
|
||||
|
||||
```markdown
|
||||
User: Using the patterns established in this skeleton, implement our first feature:
|
||||
User Authentication (login + registration + password reset)
|
||||
|
||||
Follow the skeleton's existing patterns for:
|
||||
- Route structure (match the example routes pattern)
|
||||
- Service layer (match the existing service pattern)
|
||||
- Test structure (match the example test pattern)
|
||||
- Error handling (match the existing error pattern)
|
||||
|
||||
Create a TodoWrite plan before starting implementation.
|
||||
```
|
||||
|
||||
**Step 7: Validate skeleton integrity**
|
||||
|
||||
```markdown
|
||||
User: Now that we have one real feature, verify the skeleton still works:
|
||||
1. Run full test suite
|
||||
2. Check that the CI pipeline passes
|
||||
3. Verify no skeleton patterns were broken
|
||||
4. Confirm new code follows skeleton conventions consistently
|
||||
```
|
||||
|
||||
### Phase 4: Document and Iterate
|
||||
|
||||
**Step 8: Document decisions in CLAUDE.md**
|
||||
|
||||
```markdown
|
||||
User: Update CLAUDE.md with:
|
||||
1. Which skeleton we started from (repo URL, commit hash)
|
||||
2. What we kept and why
|
||||
3. What we removed and why
|
||||
4. Any pattern deviations from the original skeleton
|
||||
5. Conventions we've added on top
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skeleton Expansion Timeline
|
||||
|
||||
```
|
||||
Skeleton (Day 1) → MVP (Week 1) → Production (Month 1)
|
||||
──────────────────────────────────────────────────────────────────────
|
||||
1 example route → 5 real routes → 20+ routes
|
||||
1 example test → 30 tests → 200+ tests
|
||||
Basic config → Env-based config → Multi-env + secrets
|
||||
SQLite/local DB → Docker PostgreSQL → Managed DB + migrations
|
||||
No CI → Basic CI → Full CI/CD pipeline
|
||||
README only → CLAUDE.md + ADRs → Full documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real-World Example: Microservice from Skeleton
|
||||
|
||||
```bash
|
||||
# 1. Clone proven skeleton
|
||||
git clone https://github.com/example/express-prisma-starter skeleton
|
||||
cd skeleton && claude
|
||||
|
||||
# 2. Audit (2 minutes)
|
||||
User: "Audit this skeleton. Is it suitable for a billing microservice?"
|
||||
# Claude: Reports deps, patterns, suitability score
|
||||
|
||||
# 3. Customize (5 minutes)
|
||||
User: "Strip examples, rename to billing-service, add our CLAUDE.md"
|
||||
# Claude: Removes demo code, updates config, adds project context
|
||||
|
||||
# 4. First feature (30 minutes)
|
||||
User: "Implement invoice creation endpoint following skeleton patterns"
|
||||
# Claude: Creates route, service, repo, tests matching skeleton conventions
|
||||
|
||||
# 5. Verify (2 minutes)
|
||||
User: "Run all tests, verify build, check skeleton patterns preserved"
|
||||
# Claude: All green, patterns consistent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Symptom | Fix |
|
||||
|---------|---------|-----|
|
||||
| Skeleton too complex | Spending more time stripping than building | Choose simpler skeleton, or build minimal one yourself |
|
||||
| Outdated dependencies | Security warnings on install | Check last commit date before cloning (< 6 months ideal) |
|
||||
| Breaking skeleton patterns | New code diverges from skeleton conventions | Add skeleton patterns to CLAUDE.md as constraints |
|
||||
| Keeping dead code | Unused example code cluttering the project | Strip ruthlessly in Phase 2, verify build after each removal |
|
||||
| No documentation | Forgetting why skeleton was chosen | Document in CLAUDE.md immediately (Phase 4) |
|
||||
|
||||
---
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- **[Vibe Coding](../ultimate-guide.md#98-vibe-coding--skeleton-projects)**: Explore before choosing a skeleton
|
||||
- **[Plan-Driven Development](./plan-driven.md)**: Plan skeleton customization before executing
|
||||
- **[TDD with Claude](./tdd-with-claude.md)**: Test-first expansion of skeleton features
|
||||
- **[Permutation Frameworks](../ultimate-guide.md#919-permutation-frameworks)**: Test multiple skeleton variants before committing
|
||||
|
||||
---
|
||||
|
||||
**Last updated**: January 2026
|
||||
Loading…
Add table
Add a link
Reference in a new issue