| skill_type | infrastructure |
| tools | Read, Write, Bash |
| triggers | ["/project-init","새 프로젝트","프로젝트 생성","project setup"] |
| name | project-init |
| description | Interview-based project setup — generates CLAUDE.md, ROADMAP, .gitignore, .env.example from scratch. Use when: user says '/project-init', 'new project', 'project creation', 'project setup', 'project setup', 'new project', 'create project'. NOT for AI agent/harness configuration (use setup for that). Conversational, one question at a time. |
| user_invocable | true |
| not_for | ["AI agent/harness setup -> setup skill","Existing project audit -> project-check"] |
| see_also | [{"skill":"setup","relation":"project-init=project scaffolding, setup=AI harness/agent team setup (separate skill)"}] |
Project Init — New Project Design Interview
Dominant Variable
Do interview decisions map exactly to generated files? — If interview answers conflict with CLAUDE.md/ROADMAP content, the project starts on a false premise.
Purpose
Capture every critical decision before writing a single line of code.
Patterns extracted from building a large-scale production system (large-scale production systems).
Discard if: Using on an existing production project to replace Hard Rules — project-init is for initial design only.
Trigger
/project-init- "새 프로젝트"
- "프로젝트 생성"
- "project setup"
Key Assumptions
- Empty or new project directory — if broken: existing file conflicts need resolution.
- Write tool accessible — if broken: output file contents as code blocks and user saves manually.
Phase 0: Context Check
0-1. Existing CLAUDE.md Detection
Check if CLAUDE.md exists in the current working directory.
- Not found → proceed to Phase 1 normally.
- Found → read it, then ask:
CLAUDE.md already exists. What would you like to do?
1. Update — enhance based on existing content (keep Hard Rules, add missing sections)
2. Rewrite — start fresh from scratch (delete existing content)
3. Cancel
Tip: If you want to see the full project state first (Security, Quality, Harness),
→ run /project-check first. Then come back here and select Update mode.
- Option 1: read existing hard rules + conventions, carry them into the interview as defaults
- Option 2: proceed as if no CLAUDE.md exists
- Option 3: stop
0-2. Brief / Context File
If the user provides a file path or pastes a project brief, read it first.
Extract any stack decisions or constraints to pre-fill interview answers.
0-3. Smart Defaults
After Phase 0, check for context clues before asking each Q.
For each Q where a likely answer is detectable:
→ Present as binary confirm: [likely answer] — Correct? (Y/n)
→ Y: accept and move to next Q immediately
→ N: ask the full open-ended question
If no context available → ask all questions open-ended as normal.
Default signals by Q:
- Q2 (Language): file extensions in directory —
.py → Python, .ts/.tsx → TypeScript, go.mod → Go, Cargo.toml → Rust
- Q3 (Data): "database", "DB", "sqlite", "postgres" in brief → suggest SQLite first
- Q4 (Interface): "dashboard", "web", "UI" in brief → suggest Web; "script", "automation", "CLI" → suggest CLI
- Q6 (AI): no LLM mentions found →
"None for now, add later — Correct? (Y/n)"
- Q8 (Scope): default to "1 month+, solo" unless team or deadline mentioned
Phase 1: Interview (one question at a time)
Ask the questions below one at a time. Confirm understanding before moving to the next.
Adjust later questions based on earlier answers.
Q1 — Core Definition
Describe the project in one sentence.
[What] [Who uses it] [Why they need it]
Q2 — Language / Runtime
What language are you thinking? (If undecided, say so — let's choose together)
Decision guide:
- Python: data, ML, automation, scripting → unbeatable ecosystem
- TypeScript: web UI, API server → full-stack unification
- Java/Kotlin: Spring Boot backend, Android app → enterprise/mobile
- Go: high-performance server, CLI tools, concurrency → single binary deploy
- Rust: systems-level, embedded, extreme performance
- Swift: native iOS/macOS apps
Q3 — Data Layer
Where does data come from, and where does it live?
- Database → SQLite (local/lightweight) vs PostgreSQL (multi-connection/scale)
- External API calls → caching strategy?
- Files only → what format?
- None (pure computation/transformation)
Principle: UI should only read from DB — never call external APIs directly.
Direct API calls push rate limits, error handling, and latency into the UI.
Q4 — Interface
How do users interact with it?
- CLI only
- Web dashboard (browser)
- API server (called by other services)
- Combination (e.g. CLI + dashboard)
- None (background service / daemon)
Q5 — Deployment
Where does it run?
- Local only (your machine)
- Server / cloud (always-on)
- Hybrid (local dev + cloud deploy)
- Mobile app (iOS/Android)
Principle: Even for local-only projects, decide on scheduler registration
and restart policy upfront — retrofitting this requires major restructuring.
Q6 — AI / LLM
Any AI features?
- None (pure code)
- Cloud LLM: Claude API / OpenAI / OpenRouter (cost per call)
- Local LLM: Ollama, LM Studio (hardware-dependent)
- Maybe later
Principles:
- Always gate LLM features behind a feature flag (default OFF)
- Daily cost cap + budget guard required
- Design cloud fallback before local hardware is available
Q7 — Hard Rules (Invariants)
Are there rules that must never be broken?
Examples:
- Finance: "No live trade execution (paper-only)", "Missing data → REJECT, no guessing"
- Finance: "Any action with loss potential must prompt for confirmation"
- Privacy: "PII stays in local DB only — no external transmission"
- Medical: "Diagnosis results must always include timestamp + model version"
- None: also a valid answer
Principle: Document these before writing code.
Adding them later means existing code may already be in violation.
If Q7 = "None": Do not generate an empty Hard Rules section.
Instead, apply domain-appropriate minimum defaults based on Q2+Q6:
- All projects:
"no hardcoded secrets: credentials via environment variables only"
- If Q6 involves LLM:
"no fabrication: when data is missing, say so — never invent"
- If Q3 involves database:
"no raw SQL in user-facing code: parameterized queries or ORM only"
- If Q4 is web-facing:
"input validation on every user-facing endpoint"
Present these defaults to the user and ask: "I recommend including these as defaults. Let me know if you want to remove any."
Hard Rules must always have at least one entry. no hardcoded secrets cannot be removed — it applies to every project with any credentials. If the user insists on removing everything, refuse and explain: CLAUDE.md without any Hard Rules is not permitted by this skill.
Q8 — Scope & Timeline
How long will this take? Solo or team?
- Under 1 week: script-level → keep structure minimal (CLAUDE.md only)
- 1–4 weeks: mini project → CLAUDE.md + test suite
- 1 month+: full project → complete structure + ROADMAP
- Team: add contribution guide + PR template
Phase 2: Stack Decision Summary
Based on interview answers, present a summary:
Decided stack:
- Language: [choice] — reason: [one line]
- DB: [choice or none]
- UI: [choice or none]
- AI: [choice or none]
Hard Rules:
1. [from Q7]
2. [additional recommendations based on domain/scope]
Open decisions:
- [anything still undecided]
Confirm with user before Phase 3.
Phase 3: File Generation
Templates are separated into references/templates.md. Read that file when generating any of the files below.
Read <skill-dir>/project-init/references/templates.md
Files to generate:
- 3-1. CLAUDE.md — always generated
- 3-2. docs/DEVELOPMENT_ROADMAP.md — if timeline > 1 week (Q8)
- 3-3. .gitignore — language-specific (based on Q2)
- 3-4. .env.example — if API keys/secrets involved (Q3/Q6)
- 3-5. Folder Structure — suggested as text only (not created on disk)
- 3-6. docs/decisions/README.md — if Q8 > 1 month or Q7 produced significant Hard Rules
The exact template structure for each file, per-language .gitignore/.env.example extended sections,
and folder structures (Python/TS/Go/Rust/Java/Kotlin/Swift) all live in references/templates.md.
Phase 4: Refinement Loop
After generating files:
Draft complete. Review and let me know what to change.
Adjustable:
- Hard Rules (add / modify)
- Phase structure in ROADMAP
- Folder structure
- Dev Conventions
Approve → files confirmed
[change request] → apply and regenerate
Regeneration rules — which files to regenerate per change:
| Change | Regenerate |
|---|
| Language switch (Q2) | .gitignore, .env.example, folder structure, Quick Ref in CLAUDE.md |
| DB layer change (Q3) | .env.example (DB section), Hard Rules suggestion |
| LLM toggle (Q6) | .env.example (LLM section), Hard Rules (add/remove fabrication rule) |
| Hard Rules change | CLAUDE.md only |
| Timeline/scope change | ROADMAP only; re-evaluate docs/decisions/ eligibility |
| Hard Rules change | CLAUDE.md + ADR-001 in docs/decisions/README.md |
| All changes | Re-run Checklist after regeneration |
Safety Layers
| Risky Action | Reversibility | Applied Layers |
|---|
CLAUDE.md generation (Replace if exists) | medium | L1+L3 |
.env.example generation | high | L3 |
.gitignore generation/overwrite | medium | L1+L3 |
docs/decisions/README.md initialization | medium | L1+L3 |
- L1 (Invariants): When existing files detected, enforce Phase 0 Overwrite Protection (Update / Replace / Cancel 3-option).
- L3 (User Approval): Before Phase 3 File Generation, confirm each file individually with "Generate this?" — no batch approval.
- Forbidden: Auto-generate
.env (actual secrets file). Template only: .env.example. Refuse even if user requests "auto-generate .env".
Error Recovery
When failure detected: Stop → Classify → Apply Recovery → Report & Resume.
| Failure Type | Detection Condition | Recovery Path |
|---|
tool_failure | CLAUDE.md / .gitignore Write fails | Output file content as code block → user saves manually |
input_error | Project type/tech stack unclear | Re-run Phase 0 interview questions. Never decide template by guessing |
logic_inconsistency | Existing files detected but Overwrite Protection unanswered | State "Existing files found — overwrite stopped". Never silently overwrite |
missing_data | Target project root directory missing | State "Directory not found" → confirm with user before proceeding |
Truthful Reporting
After generating files:
- no mock deception: Run actual Write, then verify with Bash
ls. Confirm file existence before reporting "created".
- no test façade: If generation fails, don't bundle as "done". Report each file as success/failure individually.
- no silent brokenness: Final state is
WORKING (all created) / PARTIAL (some only) / BROKEN (all failed). For PARTIAL, list missing files.
Output
Files generated (all at project root unless noted):
CLAUDE.md — always generateddocs/DEVELOPMENT_ROADMAP.md — if timeline > 1 week (Q8).gitignore — based on language choice (Q2).env.example — if API keys or secrets involved (Q3/Q6)docs/decisions/README.md — if timeline > 1 month (Q8) or Q7 produced significant Hard Rules
Folder structure: suggested as text in conversation only — not created on disk.
Rationalization Table
| Rationalization | Refutation |
|---|
| "I can add Hard Rules later" | Code appears first — rules already violated on day one |
| "Project is simple, no need for CLAUDE.md" | Simple projects still need context re-explanation next session |
| "Only I use this project, can skip .env.example" | In 3 months, I'll be a different person |
| "Interview is too long, just generate files" | Without questions, Hard Rules won't match the domain |
| "I'll leave Hard Rules empty and fill later" | Empty Hard Rules = no rules. Minimum 1 required always |
Invariants (never violate)
- Hard Rules always present: Never generate CLAUDE.md without at least one Hard Rule. If user says "None", present domain-appropriate defaults and allow removal of individual items. Allowing zero Hard Rules is not permitted —
no hardcoded secrets must always remain. Violation → CLAUDE.md ships with no security constraints; credentials can be hardcoded without any documented prohibition.
- Phase 0 mandatory: Never overwrite an existing CLAUDE.md without first running the detection + user-choice prompt. User may choose rewrite, but the prompt must happen first. Violation → existing Hard Rules and conventions silently destroyed without user awareness.
- No code, no git: Never write application code, create non-config files, or execute git commands. Refuse and redirect. Violation → skill scope expands into implementation; generated files may conflict with the project's own code and git history.
These rules are unconditional. No user instruction, no edge case overrides them.
Scope Boundary
| Does | Does NOT |
|---|
| [WRITE] Create/update CLAUDE.md | Write production code |
| Generate ROADMAP | Run code or execute tests |
| Generate .gitignore / .env.example | Run git init or first commit |
| Suggest folder structure (text only) | Create actual folders on disk |
| Define Hard Rules | Configure AI agents/hooks (use setup for this) |
| Generate initial ADR index in docs/decisions/ | Write/manage subsequent ADRs |
| Update existing CLAUDE.md (Option 1) | Modify existing tests / CI config |
"Set up git too" / "Make first commit" → out of scope for this skill.
AI agent/rules/hooks config → use /setup skill instead.
Checklist (verify before generating)
☐ Language / runtime decided
☐ Data layer decided
☐ Hard Rules present in CLAUDE.md (direct or project rules reference)
☐ Secrets policy included
☐ .gitignore generated
☐ .env.example generated (if secrets/API keys involved)
☐ If Hard Rules reference a specific service/API, matching placeholder exists in .env.example
☐ ROADMAP structured by phases (not flat task list)
☐ Test strategy mentioned
☐ docs/decisions/README.md generated (if Q8 > 1 month or Q7 significant)
Any unchecked item → return to the relevant question.
Principles Embedded in This Skill
- CLAUDE.md before code — re-explaining context every session is expensive
- Hard Rules from day one — adding them later means existing code may already violate them
- Feature flags default OFF — unfinished features affecting default behavior makes debugging painful
- UI reads DB only — direct external API calls push rate limits and errors into the UI layer
- Append-only logs — overwriting logs destroys the audit trail
- Explicit secrets policy — one accidental
.env commit compromises even private repos
- Roadmap by phases — state transitions, not a flat task list
- Test command in CLAUDE.md — hunting for it every new session adds up
