{"id":46793527,"url":"https://github.com/tommasinigiovanni/claude-code-bootstrap","last_synced_at":"2026-03-10T03:05:04.978Z","repository":{"id":342525332,"uuid":"1174263346","full_name":"tommasinigiovanni/claude-code-bootstrap","owner":"tommasinigiovanni","description":"Two drop-in CLAUDE.md wizards that turn Claude Code into a structured brainstorm partner — generating the 5 spec files your AI agent needs to build production software.","archived":false,"fork":false,"pushed_at":"2026-03-06T08:57:57.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T12:47:09.361Z","etag":null,"topics":["ai","ai-agents","claude-code","claude-skills"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tommasinigiovanni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T08:44:15.000Z","updated_at":"2026-03-06T08:58:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tommasinigiovanni/claude-code-bootstrap","commit_stats":null,"previous_names":["tommasinigiovanni/claude-code-bootstrap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tommasinigiovanni/claude-code-bootstrap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommasinigiovanni%2Fclaude-code-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommasinigiovanni%2Fclaude-code-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommasinigiovanni%2Fclaude-code-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommasinigiovanni%2Fclaude-code-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tommasinigiovanni","download_url":"https://codeload.github.com/tommasinigiovanni/claude-code-bootstrap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommasinigiovanni%2Fclaude-code-bootstrap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30322655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","claude-code","claude-skills"],"created_at":"2026-03-10T03:05:04.134Z","updated_at":"2026-03-10T03:05:04.942Z","avatar_url":"https://github.com/tommasinigiovanni.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-bootstrap\n\n**Stop vibe-coding. Start spec-coding.**\n\nTwo drop-in `CLAUDE.md` wizards that turn Claude Code into a structured brainstorm partner — and output the 5 spec files your AI agent actually needs to build production software.\n\n\u003e 97.5% of AI agents fail on real-world freelance projects.\n\u003e The difference? Structure. — [Remote Labor Index, Scale AI](https://www.remotelabor.ai/paper.pdf)\n\n---\n\n## The Problem\n\nYou open Claude Code. You type \"build me an app.\" You get… something. It looks right. It doesn't work.\n\nOr it works, but:\n- No tests\n- No clear architecture\n- No way to verify what was built\n- Next session, Claude forgets everything and starts over\n\nThe missing piece isn't better AI. It's **better specs**.\n\n## The Solution\n\nTwo wizard files that guide Claude Code through a **structured brainstorm** with you before writing a single line of code. The output is 5 files that give any AI agent the context it needs:\n\n| File | Purpose |\n|------|---------|\n| `CLAUDE.md` | Agent rules — stack, commands, style, workflow (root) |\n| `ai/PRD.md` | What we're building and what we're NOT |\n| `ai/ARCHITECTURE.md` | How the code is organized |\n| `ai/AI_RULES.md` | Conventions, testing, git, anti-patterns |\n| `ai/PLAN.md` | Step-by-step implementation with verification |\n\n\u003e **Why `ai/`?** CLAUDE.md must live in the root (Claude Code reads it from there). The other 4 files go in `ai/` to keep your project root clean. CLAUDE.md references them via `@ai/PRD.md` syntax — Claude loads them on demand, without bloating every conversation.\n\n## Two Wizards\n\n### 🚀 `CLAUDE-WIZARD.md` — New Project\n\nFor when you're starting from scratch. Drop it in an empty folder, open Claude Code, and it walks you through:\n\n```\nPhase 0: Language selection (brainstorm in any language)\nPhase 1: Vision — what are we building and for whom?\nPhase 2: Stack — which technologies and why?\nPhase 3: Rules — coding style, testing, git workflow\nPhase 4: Architecture — folder structure, data model, API\nPhase 5: Plan — phased roadmap with verification commands\nPhase 6: Generate CLAUDE.md (root) + ai/ spec files\n```\n\n### 🔍 `CLAUDE-ONBOARDING.md` — Existing Project\n\nFor when you have a codebase but never used Claude Code on it. Drop it in your project root and it:\n\n1. **Silently analyzes** your codebase (package.json, folder tree, configs, schema, CI/CD, git history)\n2. **Presents what it found** and asks \"did I get this right?\"\n3. **Asks only what the code can't tell it** — the why, the direction, the scope\n4. **Generates spec files that match reality** — not aspirational, descriptive\n\n```\nPhase 0: Automatic discovery + language selection\nPhase 1: Vision — why does this project exist?\nPhase 2: Stack confirmation — \"I found Next.js 14, is that right?\"\nPhase 3: Architecture mapping — documents what IS, not what should be\nPhase 4: Rules — what should Claude always/never do?\nPhase 5: Plan — next steps, tech debt, new features\nPhase 6: Generate CLAUDE.md (root) + ai/ spec files\n```\n\n## Quick Start\n\n### New project\n\n```bash\nmkdir my-new-project \u0026\u0026 cd my-new-project\ncurl -O https://raw.githubusercontent.com/tommasinigiovanni/claude-code-bootstrap/main/CLAUDE-WIZARD.md\nmv CLAUDE-WIZARD.md CLAUDE.md\nclaude\n```\n\n### Existing project\n\n```bash\ncd my-existing-project\ncurl -O https://raw.githubusercontent.com/tommasinigiovanni/claude-code-bootstrap/main/CLAUDE-ONBOARDING.md\nmv CLAUDE-ONBOARDING.md CLAUDE.md\nclaude\n```\n\nThat's it. Claude Code reads the `CLAUDE.md` and starts the wizard automatically.\n\n\u003e After the wizard finishes, it replaces itself with your project's actual `CLAUDE.md`.\n\n## Example Session\n\nHere's what a wizard session looks like (abbreviated):\n\n```\n🚀 Project Bootstrap Wizard\n\nHi! I'm your project bootstrap wizard.\nFirst things first: what language should we brainstorm in?\n\n\u003e Italiano\n\nPerfetto! Descrivimi il progetto in 2-3 frasi:\ncosa vuoi costruire e per chi?\n\n\u003e Un sistema di prenotazione per stampanti 3D in un FabLab.\n\u003e Gli utenti devono poter vedere gli slot liberi e prenotare.\n\nChiaro. Domanda: è un MVP per validare l'idea o deve andare in produzione?\n\n\u003e MVP, ma con fondamenta solide per poi scalare.\n\n...\n\n[after 5 phases of brainstorm]\n\n✅ Tutte le fasi confermate. Genero i 5 file:\n\n  ✓ CLAUDE.md (70 lines)\n  ✓ ai/PRD.md\n  ✓ ai/ARCHITECTURE.md\n  ✓ ai/AI_RULES.md\n  ✓ ai/PLAN.md (6 phases)\n\nIl wizard CLAUDE.md è stato sostituito col CLAUDE.md del progetto.\nUsa /compact e inizia dalla Fase 1 del piano. Buon lavoro!\n```\n\n## Example Output\n\nAfter the wizard completes, your project root looks like this:\n\n```\nmy-project/\n├── CLAUDE.md              ← 70 lines, agent rules (references @ai/ files)\n├── ai/\n│   ├── PRD.md             ← what we build, what we don't\n│   ├── ARCHITECTURE.md    ← folder tree, data model, API design\n│   ├── AI_RULES.md        ← code style, testing, git, anti-patterns\n│   └── PLAN.md            ← 6 implementation phases with verification\n└── (your code here)\n```\n\nSee the [`examples/`](examples/) folder for complete sample outputs.\n\n## Design Principles\n\n### One question at a time\nNo walls of text, no question dumps. The wizard asks one thing, listens, adapts.\n\n### Analyze first, ask later (onboarding)\nThe onboarding wizard reads your code before asking anything. It won't ask \"what framework do you use?\" when there's a `package.json` right there.\n\n### Descriptive, not aspirational\n`CLAUDE.md` documents the project **as it is**. Improvements go in `PLAN.md`. An aspirational CLAUDE.md that doesn't match reality causes more harm than no CLAUDE.md at all.\n\n### \u003c 150 lines for CLAUDE.md\n[Research shows](https://www.humanlayer.dev/blog/writing-a-good-claude-md) that Claude can follow ~150-200 instructions reliably. Claude Code's system prompt already uses ~50. Your CLAUDE.md gets the rest. Keep it tight.\n\n### Language flexibility\nInstructions for Claude are in English (better instruction-following). The brainstorm and generated files are in whatever language you choose.\n\n### Verification at every step\nEvery phase in `PLAN.md` includes a verification command. If you can't verify it, it didn't happen.\n\n## Compatibility\n\nThese wizards are compatible with:\n\n- **[GSD](https://github.com/gsd-build/get-shit-done)** — Get Shit Done framework\n- **[Superpowers](https://github.com/obra/superpowers)** — TDD workflow with subagents\n- **[BMAD](https://github.com/bmad-code-org/BMAD-METHOD)** — Multi-persona workflow\n- **[Claude Code Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)** — Official Anthropic skills system\n\nThe generated files serve as a foundation. Layer any framework on top.\n\n## FAQ\n\n**Q: Can I use this with Cursor / Copilot / other AI tools?**\nA: The wizard itself requires Claude Code. But the 5 output files work with any AI coding tool — rename `CLAUDE.md` to `AGENTS.md` for Cursor/Zed/OpenCode compatibility.\n\n**Q: What if I want to skip some phases?**\nA: Tell the wizard \"skip this phase\" — it'll use reasonable defaults and flag what was assumed.\n\n**Q: What if my project is a mess?**\nA: The onboarding wizard is designed for this. It'll be honest about what it finds and propose a cleanup plan in `PLAN.md`. No judgment, just structure.\n\n**Q: Do I need to keep the wizard file after it's done?**\nA: No. The wizard replaces itself with your project's CLAUDE.md. Keep the original wizard file somewhere if you want to bootstrap other projects.\n\n**Q: Why 5 files and not just CLAUDE.md?**\nA: CLAUDE.md must stay under 150 lines to be effective. The other 4 files live in `ai/` and are referenced via `@ai/PRD.md` syntax — Claude loads them on demand when relevant, without bloating every conversation.\n\n## Resources\n\n- [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) — Complete config collection\n- [CLAUDE.md Masterclass](https://newsletter.claudecodemasterclass.com/p/claudemd-masterclass-from-) — Deep dive on CLAUDE.md\n- [Writing a Good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) — Best practices and research\n- [Claude Code Best Practices](https://code.claude.com/docs/en/best-practices) — Official Anthropic docs\n- [Awesome Claude Code](https://github.com/hesreallyhim/awesome-claude-code) — Curated list of tools and configs\n- [Remote Labor Index](https://www.remotelabor.ai/paper.pdf) — Why 97.5% of AI agents fail\n\n## Contributing\n\nPRs welcome. If you've found patterns that make the wizard better — different phase ordering, better questions, additional output files — open an issue or PR.\n\n## License\n\nApache 2.0 — use it, fork it, adapt it.\n\n---\n\n**Author:** [Giovanni Tommasini](https://giovannitommasini.it) · [evoseed](https://evoseed.io/eng) / [AI Fabric](https://aifabric.it/en)\n\nBuilt with the same spec-driven approach this repo teaches. 🔄\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftommasinigiovanni%2Fclaude-code-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftommasinigiovanni%2Fclaude-code-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftommasinigiovanni%2Fclaude-code-bootstrap/lists"}