Cold Start Generator

Cold Start Generator

Analyzes a codebase and generates everything needed for AI-assisted autonomous development: documentation, skills, templates, and onboarding materials.

When to Use

• Setting up a new project for AI-assisted development
• Onboarding a new developer to an existing codebase
• Making any microservice codebase "AI-development ready"
• When someone says "make this repo work with Claude Code"

Primary Goal

Produce a self-contained cold-start package that allows any developer to clone a repo, point Claude Code at the cold-start doc, and immediately be productive — including autonomous feature development.

What Gets Generated

Output Package:
├── CLAUDE.md                          # Repo-level AI context (architecture, commands, conventions)
├── docs/
│   ├── COLD-START.md                  # Entry point: "Start here"
│   ├── REQUIREMENTS-TEMPLATE.md       # Machine-executable requirements format
│   ├── DEVELOPMENT-PROCESS.md         # The 4-phase process
│   └── SERVICE-MAP.md                 # Service inventory with responsibilities
└── .claude/skills/                    # Custom skills for this project
    ├── requirements-discovery/        # Tailored to this project's patterns
    │   └── SKILL.md
    └── develop-and-test/              # Tailored to this project's test infrastructure
        └── SKILL.md

Analysis Process

Step 1: Codebase Reconnaissance

Spend significant time understanding before generating anything:

1. Identify the architecture pattern:

   • Monolith? Microservices? Serverless? Monorepo?
   • How do services communicate? (HTTP, message bus, events, gRPC)
   • What's the database strategy? (shared DB, per-service DB, gateway)

2. Map the service inventory:

   • List every deployable unit
   • Identify ports, entry points, health checks
   • Map dependencies between services

3. Identify the service skeleton:

   • Read 2-3 services' entry points
   • Extract the common initialization pattern
   • Document: what's the same, what varies

4. Understand the data layer:

   • Database type (PostgreSQL, MongoDB, DynamoDB, etc.)
   • ORM or raw queries?
   • Migration strategy
   • Table/collection ownership model

5. Map the event/contract system (if any):

   • How are events defined? (Protobuf, JSON Schema, Zod, TypeScript interfaces)
   • Where do event definitions live?
   • Versioning strategy (breaking changes, backwards compat)

6. Catalog the testing approach:

   • Testing framework (vitest, jest, pytest, go test)
   • Where do tests live? (co-located, separate directory)
   • Integration test infrastructure (docker-compose, test containers)
   • CI/CD pipeline

7. Identify the deployment pipeline:

   • How does code get to production?
   • Branching strategy
   • Environment separation (dev/staging/prod)

Step 2: Generate CLAUDE.md

Create a CLAUDE.md for the repo root. Include:

# CLAUDE.md

## Project Overview
[1 paragraph: what this project does, who it's for]

## Architecture
[Diagram showing services, communication, data flow]

## Build & Development Commands
[Every command a developer needs, with explanations]

## Architecture Patterns
[The patterns that are MANDATORY — not suggestions, rules]

## Key Conventions
[Naming, file structure, error handling, logging]

## Important Files (DO NOT refactor)
[Critical files that must be preserved exactly]

## Environment Variables
[Required vars with descriptions]

## Testing
[How to run tests, what framework, where tests live]

## Deployment
[How code gets to production]

Quality standard: A developer reading ONLY this file should understand enough to make changes without breaking things.

Step 3: Generate Service Map

Document every service with:

Step 4: Generate Requirements Template

Adapt the generic requirements template to this project's patterns:

• If the project uses RabbitMQ → include message contract section with Zod
• If the project uses gRPC → include proto definition section
• If the project uses REST only → include OpenAPI schema section
• If the project uses shared DB → include table ownership section
• If the project uses per-service DB → include migration section per service
• Match the project's testing approach in the acceptance criteria section

The template must map 1:1 to code artifacts for THIS project.

Step 5: Generate Custom Skills

Create 2 skills tailored to this project:

1. requirements-discovery (customized):

• Reference this project's architecture patterns in the questions
• Include this project's event catalog in Round 2
• Include this project's table catalog in Round 2
• Reference this project's conventions in Round 3

2. develop-and-test (customized):

• Use this project's build commands
• Use this project's testing infrastructure
• Reference this project's service skeleton
• Include this project's deployment pipeline

Step 6: Generate Cold-Start Doc

Create docs/COLD-START.md:

# Cold Start — [Project Name]

## For Developers Using Claude Code

### Quick Setup (5 minutes)
1. Clone this repo
2. Install dependencies: [command]
3. Set up environment: [steps]
4. Tell Claude Code: "Read CLAUDE.md and docs/COLD-START.md"

### What Claude Code Can Do For You
- `/requirements-discovery` — Define a new feature interactively
- `/develop-and-test` — Build and test from a requirements doc
- [Other custom skills]

### Architecture at a Glance
[Simplified diagram — 10 lines max]

### Key Docs to Read First
1. [Link to most important doc]
2. [Link to second most important doc]
3. [Link to third most important doc]

### Dev Environment
[How to set up dev infrastructure for testing]

### Common Tasks
| Task | Command/Skill |
|------|--------------|
| Build a new feature | `/requirements-discovery` then `/develop-and-test` |
| Add a new service | Same, with "new-service" type in requirements |
| Fix a bug | Describe the bug, Claude Code will investigate |
| Deploy to dev | `git push origin dev` |
| Deploy to prod | Merge `dev` → `main` |

Step 7: Generate Development Process Doc

Adapt the 4-phase process to this project:

Phase 1: Requirements Discovery (interactive)
Phase 2: Architecture Validation (semi-autonomous)
Phase 3: Develop & Test (autonomous with checkpoints)
Phase 4: Deploy & Verify (semi-autonomous)

Customize each phase with:

• This project's build commands
• This project's test infrastructure
• This project's deployment pipeline
• This project's review process

Validation

Before delivering the package:

• CLAUDE.md accurately describes the architecture (cross-check with actual code)
• Service map is complete (no missing services)
• Requirements template sections map to actual code artifacts
• Custom skills reference correct file paths and patterns
• Cold-start doc can be followed by someone with zero context
• Build commands in all docs actually work
• No references to other projects' patterns (this is self-contained)

Adaptability

This skill works for:

• Node.js/TypeScript microservices (RabbitMQ, Kafka, HTTP)
• Python microservices (FastAPI, Flask, Celery)
• Go microservices (gRPC, NATS, HTTP)
• Java/Spring microservices (Spring Cloud, Kafka)
• Serverless architectures (Lambda, Cloud Functions)
• Monoliths being extracted to microservices

The key principle is the same regardless of stack: identify the repeating skeleton, document it, and make requirements map to code artifacts.