claude-code-ultimate-guide/guide/workflows/skeleton-projects.md

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 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

# 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

git clone <candidate-repo> skeleton-eval
cd skeleton-eval
claude

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)

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

# 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

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

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

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

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

# 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: Explore before choosing a skeleton
• Plan-Driven Development: Plan skeleton customization before executing
• TDD with Claude: Test-first expansion of skeleton features
• Permutation Frameworks: Test multiple skeleton variants before committing

---

Last updated: January 2026