|
| 1 | +# dev-loop |
| 2 | + |
| 3 | +[English](README.md) | **한국어** |
| 4 | + |
| 5 | +두 가지를 하나의 자기완결적 도구로 합친 Claude Code 플러그인: |
| 6 | + |
| 7 | +- **[loop-orchestrator]** — 하나의 태스크, 또는 여러 병렬 태스크를 "done"까지 |
| 8 | + 끌고 가는 방법론 기반 검증 루프 (TDD / PDCA / Reflexion). |
| 9 | +- **[dev-llm-wiki]** — 케이스 라우팅되는 시맨틱 레이어 소프트웨어 |
| 10 | + 베스트프랙티스·엣지케이스 지식 베이스, 그리고 모든 설계 결정을 거기에 |
| 11 | + 근거시키는 계획 방법론. |
| 12 | + |
| 13 | +**업스트림 loop-orchestrator에서 바뀐 단 한 가지:** 계획 단계가 더 이상 |
| 14 | +선택적·플러거블 role이 아닙니다. **번들된 `wiki-plan` 방법론에 고정**되어 — |
| 15 | +비단순 태스크는 코드를 쓰기 전에 모든 설계 결정을 번들 `wiki/`의 페이지로 |
| 16 | +라우팅해 계획합니다. 루프의 나머지는 그대로입니다. |
| 17 | + |
| 18 | +그 위에 dev-loop은 **지식 수집 루프**를 더합니다: 세션이 검증된 인사이트를 |
| 19 | +방출하면, `knowledge-flush`가 조사·중복제거·라우팅을 거쳐 위키를 키워가는 |
| 20 | +리뷰형 PR을 엽니다. |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## 설치 (글로벌) |
| 25 | + |
| 26 | +Claude Code 플러그인 마켓플레이스로 설치되므로, 스킬과 훅이 작업하는 |
| 27 | +**모든 프로젝트에 전역으로** 적용됩니다: |
| 28 | + |
| 29 | +``` |
| 30 | +/plugin marketplace add choiyounggi/dev-loop |
| 31 | +/plugin install dev-loop@dev-loop |
| 32 | +``` |
| 33 | + |
| 34 | +레포 스코프인 것은 없습니다: 위키 기반 루프, `★ Insight` 수집 지시, |
| 35 | +하베스트 훅이 어떤 레포를 열어도 활성입니다. |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## 구현 루프 |
| 40 | + |
| 41 | +두 가지 방식으로 돌립니다: |
| 42 | + |
| 43 | +- **태스크 하나 또는 기능 하나** → `loop-implement` 스킬 — **단일 구현자**. |
| 44 | + 스텝 2가 `wiki-plan`을 1회 실행해 각 태스크가 자기를 근거 짓는 위키 |
| 45 | + 페이지들을 명시한 순서 있는 태스크 목록을 만들고, 루프는 그 태스크들을 |
| 46 | + **계획의 순서대로** 실행합니다. 태스크마다: |
| 47 | + `0 완료 정의 → 1 분석 + 태스크가 명시한 위키 페이지 로드 → 3 테스트(Red) |
| 48 | + → 4 구현(페이지 지시 그대로 적용, 즉흥 금지) → 5 실행 → 6 셀프리뷰 → |
| 49 | + 6.5 독립 테스트 품질 감사 → 7 판정(적용한 WIKI 참조 보고) → 7b 반성 + |
| 50 | + 재시도(횟수 제한)`. 별도 실행자는 없습니다 — wiki-executor의 규율 |
| 51 | + (명시된 페이지만 로드, 결정 우선, 공백은 BLOCKED)이 이 루프에 흡수돼 |
| 52 | + 있습니다. |
| 53 | +- **하나의 목표를 병렬 tmux 세션들로 분할** → `orchestrate` 스킬: |
| 54 | + 인테이크 → 분해(승인 게이트) → 웨이브별 계획(wiki-plan) → 구현 + 리뷰 |
| 55 | + (각 세션이 `loop-implement` 실행) → 통합 테스트 → 머지 전 게이트 → 머지. |
| 56 | + |
| 57 | +### 스텝 2는 `wiki-plan`에 고정 |
| 58 | + |
| 59 | +`wiki-plan`은 플래너에게 **위키 라우팅 스윕**을 시킵니다: `INDEX.md`를 읽고, |
| 60 | +건드리는 각 도메인의 `index.md`를 읽고, 모든 설계 결정에 대해 그것을 소유한 |
| 61 | +페이지를 찾아 — `결정 → 위키 페이지` 맵을 기록합니다. 결정은 구체적인 |
| 62 | +값/코드로 적습니다("적절히" 금지). 그래서 구현 패스는 추측하는 대신 |
| 63 | +실행합니다. 어떤 페이지도 다루지 않는 결정은 `[no-wiki]`로 표시되어 인제스트 |
| 64 | +후보가 됩니다. 이것은 설정 가능한 role이 아니며 끌 수 없습니다. |
| 65 | + |
| 66 | +위키는 플러그인 루트에 있습니다(`wiki/`, `INDEX.md`, `AGENTS.md`, |
| 67 | +`templates/`). 위키 스킬들은 `${CLAUDE_PLUGIN_ROOT}` 기준으로 경로를 |
| 68 | +해석합니다. |
| 69 | + |
| 70 | +### 도구 설정 (선택) |
| 71 | + |
| 72 | +loop-orchestrator처럼 dev-loop은 설정 **없이도** 완전히 범용으로 돌지만, |
| 73 | +**capability role**을 실제 도구에 매핑해 루프가 그것들을 쓰게 할 수 있습니다: |
| 74 | + |
| 75 | +| Role | 매핑 대상 | |
| 76 | +|------|--------| |
| 77 | +| `verify` | 프로젝트의 **테스트 / 빌드 / QA** 명령 (루프의 실행 스텝) | |
| 78 | +| `knowledge` | 도메인/팀 **위키** 또는 knowledge MCP (외부 사실) | |
| 79 | +| `explore` | 코드/심볼 검색 (LSP, ripgrep, 소스 검색 CLI) | |
| 80 | +| `tacit` | 과거 인시던트 / danger-zone 사례 | |
| 81 | +| `design` | Figma / 비주얼 스펙 MCP (UI 작업) | |
| 82 | +| `intake` | 이슈 트래커 (orchestrate의 작업 목록) | |
| 83 | + |
| 84 | +(`plan`은 role이 **아닙니다** — 계획 단계는 `wiki-plan`에 고정입니다. 그리고 |
| 85 | +번들 베스트프랙티스 `wiki/`는 설정이 필요 없습니다. `knowledge`는 *별개의* |
| 86 | +외부 위키입니다.) |
| 87 | + |
| 88 | +**`/dev-loop:configure`**로 설정하세요 — `~/.claude/dev-loop/tools.json` |
| 89 | +(글로벌) 또는 `<repo>/.dev-loop/tools.json`(레포별, 팀 공유)을 씁니다. |
| 90 | +우선순위는 git-config 스타일: `기본값 < ~/.claude/dev-loop/tools.json < |
| 91 | +<repo>/.dev-loop/tools.json`. 아무것도 설정하지 않았다면 SessionStart 훅이 |
| 92 | +넛지합니다(최대 주 1회, 이후 없음) — `DEV_LOOP_CONFIG_NUDGE=0`으로 끌 수 |
| 93 | +있습니다. 레거시 `loop-orchestrator` 설정 경로도 fallback으로 읽습니다. |
| 94 | +`references/tool-profile.md`와 `examples/tools.example.json`을 보세요. |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## 지식 수집 루프 |
| 99 | + |
| 100 | +위키는 실제로 배운 것으로부터 자라도록 설계됐습니다. 세 개의 부품: |
| 101 | + |
| 102 | +1. **수집 (글로벌, 자동).** SessionStart 훅이 상시 지시를 주입합니다: 어떤 |
| 103 | + 레포에서든 검증된 베스트프랙티스나 남길 가치가 있는 실제 엣지케이스를 |
| 104 | + 발견하면, 간결한 `★ Insight` 블록(trigger / directive / why / evidence / |
| 105 | + domain / tags)을 방출하라. |
| 106 | + |
| 107 | +2. **하베스트 (자동, 오프라인).** Stop 훅이 세션 트랜스크립트에서 그 블록들을 |
| 108 | + 긁어 로컬 큐(`~/.dev-loop/queue/`)에 넣습니다. 위키를 편집하지도 PR을 |
| 109 | + 열지도 않습니다 — 하베스트는 저렴하고 논블로킹입니다. |
| 110 | + |
| 111 | +3. **플러시 → 검증된 PR (자동 또는 온디맨드).** 큐는 `knowledge-flush` |
| 112 | + 파이프라인이 비웁니다. **각** 후보에 대해, PR 전에 반드시: |
| 113 | + - 실제 출처(공식 문서, 1차 레퍼런스)에 대고 베스트프랙티스를 **조사·검증** |
| 114 | + 하고 신뢰도를 부여합니다 (verified / field-tested / unverified — 지어낸 |
| 115 | + 인용은 절대 금지), |
| 116 | + - 병합할 중복과 링크할 페이지를 찾아 **기존 레이어를 확인**하고, |
| 117 | + - **타깃 레이어/카테고리를 결정**(또는 새 카테고리를 정당화)한 뒤, |
| 118 | + - `wiki-ingest`를 실행하고 `INGEST_REPORT.md`를 씁니다. |
| 119 | + |
| 120 | + 플러시당 **PR 하나**를 열고 **절대 자동 머지하지 않습니다**. 각 기여자의 |
| 121 | + PR은 **본인의 git/gh 신원으로** 커밋·오픈됩니다(하드코딩된 계정도, |
| 122 | + 어시스턴트도 아님). 레포 소유자가 열린 `dev-loop:knowledge` PR들을 |
| 123 | + 리뷰해 각각 머지하거나 반려합니다. |
| 124 | + |
| 125 | + 실행되는 두 가지 경로: |
| 126 | + - **자동** — `hooks/auto-flush.sh` Stop 훅이 큐가 임계치를 넘고 rate-limit |
| 127 | + 윈도우가 지났을 때 분리된 headless `claude` 실행으로 파이프라인을 |
| 128 | + 발화합니다. 아무것도 하지 않아도 PR이 나타납니다. 가드: |
| 129 | + 킬 스위치 `DEV_LOOP_AUTOFLUSH=0`, `DEV_LOOP_AUTOFLUSH_INTERVAL`(기본 |
| 130 | + 3600초)당 1회, 대기 항목 `DEV_LOOP_AUTOFLUSH_MIN`(기본 3)개 이상일 때만, |
| 131 | + single-flight 잠금, 재귀 안전. `claude` + `gh`가 PATH에 있고 gh 인증이 |
| 132 | + 필요합니다. 하나라도 없으면 조용히 no-op — 수동으로 fallback. |
| 133 | + - **수동** — 언제든 `/dev-loop:knowledge-flush`로 큐를 지금 비웁니다. |
| 134 | + |
| 135 | +### 이 순서는 훅으로 강제됩니다 |
| 136 | + |
| 137 | +`hooks/pre-flush-pr-gate.sh`(PreToolUse)는 knowledge 브랜치에서 |
| 138 | +`INGEST_REPORT.md`가 존재하고 세 섹션(`## Verified best-practice`, |
| 139 | +`## Existing-layer check`, `## Routing decision`)이 실제 내용으로 채워져 |
| 140 | +있지 않으면 `gh pr create`를 **차단**합니다. 게이트는 knowledge-flush PR로 |
| 141 | +좁게 스코프되어, 다른 레포의 일반 `gh pr create`에는 절대 간섭하지 않습니다. |
| 142 | + |
| 143 | +--- |
| 144 | + |
| 145 | +## 스킬 |
| 146 | + |
| 147 | +| 스킬 | 역할 | |
| 148 | +|-------|------| |
| 149 | +| `loop-implement` | **단일 구현자** — wiki-plan을 소비해 태스크를 순서대로 (각 태스크가 명시한 위키 페이지를 로드하며) 검증 루프로 실행. 계획 단계 = wiki-plan. | |
| 150 | +| `orchestrate` | 하나의 목표를 병렬 세션들로 분할, 각 세션은 loop-implement 실행. | |
| 151 | +| `wiki-plan` | **고정된 계획 방법론** — 각 결정을 위키 페이지로 라우팅, 순서 있는 페이지-내비게이션 태스크로 분해. | |
| 152 | +| `wiki-ingest` | 검증된 지식을 올바른 시맨틱 레이어에 추가 (knowledge-flush가 사용). | |
| 153 | +| `wiki-query` | 위키에서 인용과 함께 질문에 답변. | |
| 154 | +| `wiki-lint` | 위키 건강 점검. | |
| 155 | +| `knowledge-flush` | 큐의 인사이트를 조사 + 검증 + 라우팅 → 리뷰형 위키 PR 하나. | |
| 156 | +| `configure` | capability-role 도구 프로파일 설정 (위키·테스트 명령 등 매핑). | |
| 157 | + |
| 158 | +## 구조 |
| 159 | + |
| 160 | +``` |
| 161 | +dev-loop/ |
| 162 | +├── .claude-plugin/{plugin,marketplace}.json |
| 163 | +├── AGENTS.md INDEX.md templates/ # 위키 스키마 + 라우팅 진입점 + 페이지 템플릿 |
| 164 | +├── wiki/ # 10개 도메인 시맨틱 레이어 지식 베이스 |
| 165 | +├── skills/ # 위의 스킬 8종 (사용자 호출 가능; / 메뉴에 스킬 이름으로 표시) |
| 166 | +├── agents/test-quality-auditor.md # 번들된 독립 테스트 감사자 (루프 스텝 6.5) |
| 167 | +├── hooks/ |
| 168 | +│ ├── hooks.json |
| 169 | +│ ├── preflight.sh # SessionStart: git/tmux/jq 어드바이저리 |
| 170 | +│ ├── insight-instruction.sh # SessionStart: ★ Insight 수집 지시 주입 (글로벌) |
| 171 | +│ ├── config-nudge.sh # SessionStart: 미설정 시 /dev-loop:configure 넛지 (주간) |
| 172 | +│ ├── loop-gate.sh # Stop: 검증 루프 무결성 게이트 |
| 173 | +│ ├── harvest-insights.sh + harvest.js # Stop: 인사이트 하베스트 → 큐 |
| 174 | +│ ├── auto-flush.sh # Stop: knowledge-flush 자동 실행 (가드됨) → PR |
| 175 | +│ └── pre-flush-pr-gate.sh # PreToolUse: 플러시 사전 PR 파이프라인 강제 |
| 176 | +├── scripts/resolve-tools.sh # capability-role 프로파일 리졸버 (`plan` role 없음) |
| 177 | +├── references/tool-profile.md |
| 178 | +└── docs/ # 물려받은 설계 노트 (loop-orchestrator 계보) |
| 179 | +``` |
| 180 | + |
| 181 | +--- |
| 182 | + |
| 183 | +## 기여 표시 (Attribution) |
| 184 | + |
| 185 | +Knowledge PR(수동이든 자동이든)은 **각 기여자 본인의 git/gh 신원으로** |
| 186 | +커밋됩니다 — 하드코딩된 계정도 어시스턴트도 아니며, `Co-Authored-By` |
| 187 | +트레일러도 없습니다. 모든 기여자는 자기 계정으로 PR을 열고, 레포 소유자가 |
| 188 | +리뷰해 머지/반려합니다. |
| 189 | + |
| 190 | +## 계보 & 라이선스 |
| 191 | + |
| 192 | +**loop-orchestrator**와 **dev-llm-wiki**(둘 다 choiyounggi 작)에서 |
| 193 | +포크했습니다. 물려받은 루프 설계는 `docs/`를 보세요 (주의: 그 문서들은 위에 |
| 194 | +설명한 계획-단계-고정 변경 이전에 쓰였습니다). MIT — `LICENSE` 참고. |
| 195 | + |
| 196 | +[loop-orchestrator]: https://github.com/choiyounggi/loop-orchestrator |
| 197 | +[dev-llm-wiki]: https://github.com/choiyounggi/dev-llm-wiki |
0 commit comments