프로젝트 Bootstrap — Blank Repo에서 시작하는 방법

핵심 원칙

상태를 chat memory가 아니라 파일과 git history에 저장한다.

harness 최적화보다 shipping 우선. agent가 실패할 때만 harness를 개선한다.

업계 공통 4단계 Bootstrap (agentic-harness-bootstrap)

Phase 0: Discover  — 스택, 구조, 컨벤션 탐지
Phase 1: Analyze   — 아키텍처 패턴 추론
Phase 2: Generate  — harness 파일 생성
Phase 3: Verify    — 모든 것이 작동하는지 검증

기존 파일은 덮어쓰지 않고 읽어서 보존, 새 섹션만 merge.

두 가지 Bootstrap 방식

방식 A — Initializer agent가 전담 (Anthropic 패턴)

1. 인간: "프로젝트 목표 설명"
2. Initializer agent 생성:
   - CLAUDE.md, init.sh, claude_progress.log (빈 상태)
   - feature_list.json (전부 passes: false)
   - 초기 git commit
3. 이후 Coding agent가 feature 하나씩 구현

방식 B — 인간 설계 후 전달 (내 방식)

1. 설계하자 (Desktop): architecture.md, feature_list.md, skill/
2. context-bridge.md 업데이트 (결정된 것 기록)
3. Claude Code: CLAUDE.md + init.sh 생성 후 구현 시작

파일 생성 순서 (내 시스템 기준)

Phase 1 — 없으면 막힘 (즉시 필요)

[Desktop - 설계하자]
design/{project}/architecture.md
design/{project}/decisions.md
projects/{project}/feature_list.md
projects/{project}/context-bridge.md

[Claude Code - 첫 세션]
CLAUDE.md          ← agent 시작점 (vault 경로 + 세션 규칙)
init.sh            ← 환경 재현 가능성
.gitignore
claude_progress.log (빈 상태)
git init + 초기 commit

Phase 2 — 구현 시작 전

tests/test_architecture.py  ← AC test (레이어 규칙)
.github/workflows/ci.yml    ← CI

Phase 3 — 패턴이 반복될 때

projects/{project}/skill/{name}.md
projects/{project}/troubleshooting.md

Phase 4 — 프로젝트 성숙 시

docs/adr/           ← ADR 상세 문서
gc-checklist.md     ← 주간 drift 점검

CLAUDE.md 최소 구조 (60줄 이하 권장)

# {project-name}

## Vault 경로
knowledge vault: /home/server1/g-drive/root/knowledge/

## 시작 시 읽을 것
1. projects/{name}/context-bridge.md
2. projects/{name}/feature_list.md
3. claude_progress.log (마지막 항목)

## 규칙
- tests/test_architecture.py 항상 통과시킬 것
- 새 결정 → design/{name}/decisions.md append
- 막히면 → context-bridge.md "Desktop에서 결정해야 할 것" 추가

## 세션 종료 전
1. claude_progress.log 업데이트
2. feature_list.md 상태 갱신
3. context-bridge.md 업데이트
4. git commit

실전 교훈

• CLAUDE.md 60줄 이하 — 더 길면 agent가 중요한 규칙을 잊음
• feature_list는 JSON이 MD보다 훼손 방지에 좋음
• init.sh가 없으면 매 세션 환경 세팅에 토큰 낭비
• 초기 commit이 없으면 revert 기준점이 없음

관련 개념

• initializer-coding-agent-pattern — Anthropic의 initializer + coding agent 패턴
• architectural-constraints — AC test 설계
• harness-layer-structure — 전체 레이어 구조
• industry-harness-trends-2026 — 업계 트렌드

시각화

![[project-bootstrap-flow.svg]]