Project Init

Project Init — New Project Design Interview

Dominant Variable

인터뷰에서 수집한 결정이 생성 파일에 정확히 반영되는가 — 인터뷰 답변과 CLAUDE.md/ROADMAP 내용이 불일치하면 프로젝트가 잘못된 전제 위에서 시작.

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: 이미 운영 중인 프로덕션 프로젝트에서 Hard Rules 교체 목적으로 사용 — project-init은 초기 설계 전용.

Trigger

• /project-init
• "새 프로젝트"
• "프로젝트 생성"
• "project setup"

---

Key Assumptions

1. 빈 또는 신규 프로젝트 디렉토리 — 깨지면: 기존 파일 충돌 해소 필요.
2. Write 도구 접근 가능 — 깨지면: 파일 내용만 출력하고 유저가 수동 저장.

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가 이미 존재합니다. 어떻게 할까요?

1. 업데이트 — 기존 내용을 기반으로 보강 (Hard Rules 유지, 누락 섹션 추가)
2. 재작성 — 처음부터 새로 작성 (기존 내용 삭제)
3. 취소

팁: 현재 프로젝트 전체 상태(Security, Quality, Harness 포함)를 먼저 보고 싶다면 → /project-check 를 먼저 실행하세요. 이후 여기서 Update 모드로 돌아오면 됩니다. ```

• 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] — 맞나요? (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, 나중에 추가 — 맞나요? (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: "이 정도는 기본으로 넣는 걸 추천합니다. 제거할 항목 있으면 말씀해주세요."

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

3-1. CLAUDE.md

Generate at project root using this structure:

# [Project Name] v1.0

## Hard Rules (never bend)
{Conditional — check before generating:
  `.claude/rules/project rules` exists →
    Hard Rules → see [.claude/rules/project rules](.claude/rules/project rules)
  Does NOT exist →
    - [each rule from Q7 + domain defaults, listed directly]
}

## Quick Ref
- Entry: [auto-filled from Q2: Python→`python {main}.py`, TS→`npx ts-node src/index.ts`, Go→`go run cmd/{app}/main.go`, Rust→`cargo run`, Java→`./gradlew bootRun`]
- Tests: [auto-filled from Q2: Python→`pytest tests/ -q`, TS→`npm test`, Go→`go test ./...`, Rust→`cargo test`, Java→`./gradlew test`]
- [additional references]

## Secrets Policy
- Never read, print, or log `.env` — use environment variables only.
- Never commit `.env` — `.env.example` is the template (no real values).
- New API keys → add placeholder to `.env.example` + load via env var.

## Dev Conventions
- Tests before merge. Never declare done without a passing test.
- New features: opt-in via env var, default OFF.
- Logs: append-only (never overwrite log/jsonl files).
- Commits: one logical change per commit — independently revertable.
- Commit only when explicitly requested.

## Compact Instructions
Preserve on compaction:
1. Hard Rules
2. Current active branch / uncommitted file list
3. Pending tasks and their status
4. Active errors or bugs being investigated
5. Dev Conventions
6. File paths modified in this session

3-2. docs/DEVELOPMENT_ROADMAP.md

# [Project Name] — Development Roadmap

## Phase 1: Foundation (goal: core functionality working)
- [ ] 1-1. Project structure setup
- [ ] 1-2. DB schema / data layer
- [ ] 1-3. [Core feature #1]
- [ ] 1-4. Basic test suite

## Phase 2: Core Features
- [ ] 2-1. [Main feature]
- [ ] 2-2. [Main feature]

## Phase 3: Polish
- [ ] 3-1. Error handling hardening
- [ ] 3-2. Performance optimization
- [ ] 3-3. Documentation

## Backlog (unscheduled)
- [ ] [Future items]

3-3. .gitignore

Generate at project root based on language:

Python:

# Environment
.env
.env.local
venv/
.venv/
__pycache__/
*.pyc
*.pyo
*.pyd

# Outputs & artifacts
outputs/
*.log
*.jsonl

# IDE
.vscode/
.idea/
*.egg-info/
dist/
build/
.pytest_cache/
.mypy_cache/

TypeScript / JavaScript:

# Environment
.env
.env.local
.env.*.local

# Dependencies
node_modules/

# Build
.next/
dist/
build/
out/

# Logs
*.log
npm-debug.log*

# IDE
.vscode/
.idea/

Go:

.env
*.exe
*.exe~
*.test
*.out
vendor/

Rust:

.env
/target/
Cargo.lock   # remove this line if publishing a library

Java / Kotlin:

.env
.gradle/
build/
out/
*.class
*.jar
.idea/
*.iml
local.properties

Swift:

.env
.build/
*.xcworkspace/xcuserdata/
DerivedData/
*.ipa
*.dSYM.zip

---

3-4. .env.example

Generate based on what was decided in Q6 (AI/LLM) and Q3 (data layer):

# === API Keys ===
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# OPENROUTER_API_KEY=

# === Database ===
# DATABASE_URL=sqlite:///app.db
# POSTGRES_URL=

# === Feature Flags (default OFF) ===
# LLM_ENABLED=0
# [FEATURE_NAME]_ENABLED=0

# === App Config ===
# LOG_LEVEL=INFO
# PORT=8000

Only include sections relevant to the project's decided stack. Leave all values empty — this file is a template, never a config.

Extended sections (conditional on Q3/Q6 answers):

# === OAuth / Auth (if auth layer selected in Q3) ===
# OAUTH_CLIENT_ID=
# OAUTH_CLIENT_SECRET=
# JWT_SECRET=

# === External Services (if external APIs in Q6) ===
# STRIPE_API_KEY=
# SENDGRID_API_KEY=
# AWS_ACCESS_KEY_ID=
# AWS_SECRET_ACCESS_KEY=
# AWS_REGION=

# === Monitoring (if production deployment planned) ===
# SENTRY_DSN=
# DATADOG_API_KEY=

Security Baseline (always include):

# === Security Notes ===
# 1. Copy this file to .env and fill real values
# 2. NEVER commit .env — only .env.example
# 3. Rotate keys if accidentally exposed
# 4. Use least-privilege scopes for all API keys

Swift projects: same structure — include only sections relevant to your app's API dependencies:

# === API Keys ===
# API_KEY=

# === Feature Flags (default OFF) ===
# FEATURE_NAME_ENABLED=0

# === App Config ===
# BASE_URL=https://api.example.com

---

3-6. docs/decisions/README.md (optional)

Generate if Q8 timeline > 1 month OR if Q7 produced significant Hard Rules:

# Architecture Decision Records

Decisions that shaped this project. Add an entry whenever you:
add a new dependency, replace an existing pattern, change the data model, or restructure agents.

## Template
\`\`\`markdown
# [Decision Title]
## Context: 왜 이 결정이 필요한가
## Decision: 무엇을 선택했는가
## Consequences: 트레이드오프, 알려진 제약
\`\`\`

## Decisions

### ADR-001: Initial Stack Decisions
**Context**: Stack and rules decided during `/project-init` interview.
**Decision**: Language: [Q2 answer], Data: [Q3 answer], Interface: [Q4 answer], AI: [Q6 answer]
**Hard Rules origin**: [from Q7 — why each rule exists]

---

3-5. Folder Structure (reference only — not generated)

Auto-select based on language. Combine for multi-language projects.

Python (data / automation / backend):

[project]/
├── CLAUDE.md
├── .env.example
├── requirements.txt          # pip install -r requirements.txt
├── [main_entry].py
├── [core_module]/            # core logic
├── tests/                    # pytest
│   └── conftest.py
├── docs/
│   ├── INDEX.md
│   └── DEVELOPMENT_ROADMAP.md
├── scripts/                  # utility scripts
├── config/                   # YAML/JSON config
└── outputs/                  # artifacts (.gitignore)

TypeScript — Next.js / Full-stack web:

[project]/
├── CLAUDE.md
├── .env.example
├── package.json
├── tsconfig.json
├── next.config.ts            # if using Next.js
├── src/
│   ├── app/                  # App Router (Next.js 14+)
│   ├── components/
│   ├── lib/                  # utils, DB client
│   └── types/
├── tests/                    # Vitest / Jest
├── docs/
│   └── DEVELOPMENT_ROADMAP.md
└── scripts/

TypeScript — API server (Express / Fastify / Hono):

[project]/
├── CLAUDE.md
├── .env.example
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # entrypoint
│   ├── routes/
│   ├── services/             # business logic
│   ├── middleware/
│   └── types/
├── tests/
└── docs/
    └── DEVELOPMENT_ROADMAP.md

Java / Kotlin — Spring Boot (backend API):

[project]/
├── CLAUDE.md
├── .env.example
├── build.gradle.kts           # or pom.xml (Maven)
├── settings.gradle.kts
├── src/
│   ├── main/
│   │   ├── kotlin/            # or java/
│   │   │   └── com/[pkg]/
│   │   │       ├── Application.kt
│   │   │       ├── controller/
│   │   │       ├── service/
│   │   │       ├── repository/
│   │   │       └── domain/
│   │   └── resources/
│   │       └── application.yml
│   └── test/
│       └── kotlin/
│           └── com/[pkg]/
├── docs/
│   └── DEVELOPMENT_ROADMAP.md
└── scripts/

Kotlin — Android:

[project]/
├── CLAUDE.md
├── build.gradle.kts
├── settings.gradle.kts
├── app/
│   ├── build.gradle.kts
│   └── src/
│       ├── main/
│       │   ├── kotlin/com/[pkg]/
│       │   │   ├── MainActivity.kt
│       │   │   ├── ui/
│       │   │   ├── viewmodel/
│       │   │   └── data/
│       │   └── res/
│       └── test/
├── docs/
│   └── DEVELOPMENT_ROADMAP.md
└── scripts/

Go (CLI / high-performance server):

[project]/
├── CLAUDE.md
├── .env.example
├── go.mod
├── go.sum
├── cmd/
│   └── [app]/
│       └── main.go           # entrypoint
├── internal/                 # unexported packages
│   └── [feature]/
├── pkg/                      # exported packages
├── tests/
└── docs/
    └── DEVELOPMENT_ROADMAP.md

Rust (systems / CLI):

[project]/
├── CLAUDE.md
├── .env.example
├── Cargo.toml
├── src/
│   ├── main.rs               # or lib.rs for libraries
│   └── [module]/
│       └── mod.rs
├── tests/                    # integration tests
├── benches/                  # benchmarks (optional)
└── docs/
    └── DEVELOPMENT_ROADMAP.md

Swift (iOS / macOS):

[project]/
├── CLAUDE.md
├── [Project].xcodeproj/      # or Package.swift (SPM)
├── Sources/
│   └── [Target]/
├── Tests/
│   └── [Target]Tests/
└── docs/
    └── DEVELOPMENT_ROADMAP.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 생성 (기존 존재 시 Replace) | medium | L1+L3

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AlexZio00
• Source: AlexZio00/sovereign-skills
• License: MIT
• Homepage: https://x.com/AlexZio00

Install and usage instructions live in the source repository linked above.