# Project Init

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

- Skill: `alexzio00/project-init-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add alexzio00/project-init-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexzio00/project-init-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: AlexZio00 (https://skillmd.com/u/alexzio00)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/alexzio00/project-init-2

---


# 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:**

| 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; also update ADR-001 in docs/decisions/README.md if that file exists (Q8 > 1 month OR Q7 was flagged significant — same eligibility as 3-6) |
| Timeline/scope change | ROADMAP only; re-evaluate docs/decisions/ eligibility |
| 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:
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

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

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

| 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