Project Init

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

1. Empty or new project directory — if broken: existing file conflicts need resolution.
2. 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:

Safety Layers

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

Truthful Reporting

After generating files:

1. no mock deception: Run actual Write, then verify with Bash ls. Confirm file existence before reporting "created".
2. no test façade: If generation fails, don't bundle as "done". Report each file as success/failure individually.
3. 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 generated
• docs/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

Invariants (never violate)

1. 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.
2. 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.
3. 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

"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