기획-개발 자동화 루프, 한눈에
기획(BIS-Docs) → GitHub 이슈 → 개발 하네스(BisFramework) → QA → 기획 역반영으로 도는 루프의 전체 그림입니다. 단계 안의 검토 기준은 각 스킬이 담당하고, 이 가이드는 단계 사이(이음새)에서 확인할 것을 다룹니다.
겹쳐 도는 3개의 루프
CRITICAL·HIGH 0건까지 반복하고, 자동 개선이 불가한 항목은 「결정 필요」로 분리해 결정권자에게 넘깁니다.
수용 기준 대비로 판정하고, 하네스에는 반복 중단 장치(🚫)가 있습니다.
근거 링크 · 버전 좌표(plan vN.M) · 완료 SHA 원격 도달성이 강제됩니다. 루프가 돌수록 기획안이 단단해지는 축입니다.
루프의 수렴 방향성은 불변 좌표 체계가 보장합니다 — 모든 산출물이 plan vN.M · dev@<hash> · #이슈번호 · 코멘트 permalink로 서로를 가리키므로, 좌표가 어긋나는 지점이 곧 드리프트 신호입니다.
자산이 사는 곳 (혼동 주의)
별도 표기가 없으면 BIS-Docs 커밋 자산입니다. Odyssey(기획 자동화 실행기)는 이 루프의 스킬 소유처가 아닙니다 — bs-plan-issue-sync canonical track이 대조하는 BisFramework/_odyssey/ 상태(실행 머신 로컬)의 실행기입니다.
| 위치 | 자산 | 공유 범위 |
|---|---|---|
| BIS-Docs .claude/ 커밋 |
bs-planning-boundary · bs-plan-review · bs-issue-comment · bs-plan-update · bs-plan-issue-sync · bs-proto-author + boundary hook 2종 | 팀 공유 — 이 저장소에서 세션을 열면 자동 적용 |
| 운영자 로컬 저장소 밖 |
bis-docs-doc-qa · bs-qa-in-dev · bs-staging-qa-parallel | 운영자 머신별 설치 — 커밋돼 있지 않음 |
| BisFramework | 개발 하네스 파이프라인 · planning-comment-router 수신 계약 | 개발 측 |
단계 ↔ 담당 자산
| 루프 단계 | 담당 자산 | 위치 | 강제 수준 |
|---|---|---|---|
| 기획 작성 경계 | bs-planning-boundary + planning-boundary-gate.sh | BIS-Docs | HARD(쓰기 차단) + SOFT(자가 체크) |
| 문서 정합성 | bis-docs-doc-qa | 운영자 로컬 | 게이트 |
| 이슈 등록 전 검토 | bs-plan-review (R0~R8) | BIS-Docs | 게이트 — CRITICAL·HIGH 0건 |
| 이슈 본문·코멘트 | bs-issue-comment | BIS-Docs | 작성 정본 + 게시는 사람 승인 |
| 개발 구현 | 개발 하네스 (BisFramework) | BisFramework | 하네스 자율 (harness_autonomous) |
| In Dev QA | bs-qa-in-dev | 운영자 로컬 | dry-run 기본, FAIL은 사람 검토 |
| staging QA | bs-staging-qa-parallel | 운영자 로컬 | 참조 |
| 기획 반영 (단건) | bs-plan-update | BIS-Docs | 근거·version·완료 좌표 강제 |
| 일괄 수거·감사 | bs-plan-issue-sync | BIS-Docs | fail-closed scan (read-only) |
다음 페이지에서: 전체 플로우 다이어그램 · 역반영 3분기 · 리스크 검토 · 전환 체크리스트
전체 플로우 다이어그램
기획 수렴(①)부터 역반영(⑤)까지 — 게이트가 어디에 서 있는지, 사람이 어디서 개입하는지를 한 장으로 그린 다이어그램입니다.
칩으로 표시한 스킬은 별도 표기가 없으면 BIS-Docs .claude/ 커밋 자산입니다. · 운영자 로컬 표기 2종 (bis-docs-doc-qa · bs-qa-in-dev)만 저장소 밖 러너이고, Odyssey 소속 스킬은 이 다이어그램에 없습니다 — 자산이 사는 곳 참조.
경로 요약
- ①에서 기획이 수렴(L1)한 뒤 main 머지로만 하네스에 전달됩니다 — main에 없으면 하네스가 보지 못합니다.
- ②의 Ready 전환 + 개발 할당(사람)이 착수 큐 신호입니다. 열린 🙋 결정 요청이 있으면 Ready 금지.
- ③은 착수 전 실측 대조로 본문 전제를 재확인하고, 다르면 구현하지 않고 blocked를 보고합니다.
- ④의 FAIL은 ⑤에서 3분기(버그 / 기획 변경 / 결정 필요)로 라우팅됩니다 — 역반영 3분기.
- ⑤의 📌 경로가 L3 플라이휠 — 기획 version이 오르고 TC가 신좌표로 재생성된 뒤 재검증합니다.
mermaid 소스는 md 정본 §3과 동일합니다. 렌더링이 안 되는 환경에서는 다이어그램 자리에 소스 텍스트가 표시됩니다.
역반영 상세 — 발견 분류 3분기
QA·개발에서 나온 발견은 분류가 먼저입니다. 분류가 틀리면 루프가 엉뚱한 곳으로 돕니다 — spec-stale을 버그로 보내면 개발 재작업 낭비, 버그를 기획 변경으로 보내면 기획안 오염. 판정 주체는 기획입니다.
| 분류 | 신호 | 처리 |
|---|---|---|
| 버그 | 기획대로인데 동작 이상 | 일반 코멘트(기획 변경 아님) → 재작업 → 수정 후 🧪 QA 확인 요청 |
| spec-stale / 기획 변경 | 기획이 낡았거나 변경 합의 | 📌 기획 변경(추가·수정·삭제) → bs-plan-update → TC 파급 |
| 결정 필요 | 기획에 없는 케이스 | 🙋 결정 요청(@대상+기한) → ✅ 결정 후 진행 |
버전 파급 주의
- Major 판정(사실상 다른 문서)이면 bs-plan-update는 제자리 반영하지 않고 중단·핸드오프합니다 — 기존 단위 archive 보존 → 새 단위 반영 → supersedes 연결의 별도 절차 (기획 운영 계약 §4.3).
- 수치·기대값 정정은 Patch가 아니라 Minor — QA TC가 대조하는 값(임계값·산식·기간·상태값)이 바뀌면 표기 실수 정정이라도 영향 TC 재생성 신호를 남깁니다.
- TC 파급은 유형으로 판정합니다: 추가=TC 신규 · 수정=영향 TC 재생성 · 삭제=TC 폐기.
mermaid 소스는 md 정본 §4와 동일합니다.
리스크 검토 — 막힌 곳과 공백
루프의 구조적 결함은 없습니다. 단계 내부는 게이트가 촘촘하고, 공백 7건은 전부 아직 규약화되지 않은 이음새·주기에 있습니다 — 그래서 대응도 새 검토 기준이 아니라 전환 체크리스트입니다.
이미 방어돼 있는 리스크
| 리스크 | 방어 장치 |
|---|---|
| 기획이 HOW 침범 (코드 지정·방식 지정) | boundary hook HARD(쓰기 전후) + 스킬 자가 체크 + R8 재검 — 3중 |
| 기획 전제 ≠ 코드 현실 | R1 현실대조(검증ref 고정) + 하네스 착수 전 실측 대조 |
| 수용 기준 부재 · 형식 통과 | R5 CRITICAL + 버튼 숨김·no-op 통과 기준 반려 + validation/ 구현 입력 제외 |
| 근거 없는 변경 · 유령 완료 | 근거 링크 없는 version 증가 금지, 원격 미도달 SHA 완료 회신 금지 |
| 종결 후 코멘트 몰래 반영 | post_close_pending — 증명 불가는 fail-closed |
| 프롬프트 인젝션 (이슈 본문·index.yaml) | 명령 안전 규칙 + path_safety 계약 + In Dev QA nonce 마커 |
| 무승인 GitHub 변이 | 게시·상태 변경은 현재 턴 승인만 유효, 백그라운드 변이 루프 비활성 |
| 보안·권한·PII 자동 확정 | R7 human_gate 라우팅 + issue-sync 자동 제안 차단 목록 |
공백·주의 7건
| # | 공백 | 권고 |
|---|---|---|
| G1 | 작성 규약 ↔ 수신 계약 비대칭. 태그 5종은 작성 규약일 뿐, 실시간 하네스(router) 수신 계약에는 태그 파싱 규칙이 아직 없고, 하네스는 무태그 코멘트까지 전부 읽고 행동 근거로 씁니다 (무태그 착수 승인 코멘트로 #309 자동 착수 실측). | 태그 수신 규칙의 계약 편입 협의. 그 전까지 무태그 위생 점검 (T4) |
| G2 | 리뷰 신선도. bs-plan-review는 등록 직전 1회 게이트 — Ready 대기가 길어져 dev가 크게 바뀌면 R1 전제가 다시 낡습니다. 리포트 자체의 유효기간 규칙이 없습니다. | 리뷰 후 타깃 레포 주요 변경 시 R1만 재실행 (T2 신규) |
| G3 | stale TC 미검출. Minor 이상 변경 시 "TC 재생성 필요" 신호만 주고 끝 — TC에 찍힌 plan vN.M이 현재 version과 어긋난 채 재검증에 쓰여도 잡는 장치가 없습니다. 공백 중 유일하게 "기획 의도와 다른 기준으로 검증이 통과"할 수 있는 구멍. | 주기 점검: TC 좌표 vs 현재 version 대조 (T5 신규) — 1순위 |
| G4 | 역반영 핑퐁 상한 부재. L1·하네스에는 수렴 장치가 있는데, L3만 같은 대상이 FAIL→📌→재생성→FAIL을 왕복해도 카운터가 없습니다. | 같은 대상 2회 이상 왕복 시 🙋로 강제 전환 (T5 신규) |
| G5 | 스위퍼 무주기. bs-plan-issue-sync scan이 안 돌면 놓친 📌 대기·open 🙋·post_close_pending이 계속 잠복합니다. 스킬은 "한 번씩 몰아서"라고만 정의. | 주기 확정 — 주 1회 권장. scan은 read-only라 승인 부담 없음 (T5) |
| G6 | 공통 계약 파급. bs-plan-update는 "근거가 말한 범위만" 단일 단위 반영 — common/ 계약 변경이 소비 패키지로 전파됐는지 확인하는 절차가 반영 축에 없습니다. | 반영 대상이 common/이면 소비 패키지 열거·파급 확인 (T4 신규) |
| G7 | 공유 원장 계약 정본 미선언. bs-plan-issue-sync와 기획 자동화 실행기(Odyssey)가 캐노니컬 원장 형식(project.manifest · task-matrix · revisions)을 공유하지만, 계약 정본·버전 참조 선언이 없어 실행기 쪽 형식이 바뀌면 BIS-Docs 검증기가 조용히 낡습니다 (근거: bs-plan-issue-sync/references/artifact-contract.md + 실행기 저장소 대조, 2026-08-02). | artifact-contract.md를 공유 계약 정본으로 지정하고 양쪽이 그 버전을 참조 |
각 공백의 근거(스킬 정본 조항)는 md 정본 §5.2 표에 있습니다. 개발 하네스 내부 동작 관련 항목은 BisFramework 측 정본 확인이 필요한 추정을 포함합니다.
전환 게이트 체크리스트 T1~T5
단계 안의 내용 검토는 각 스킬이 담당합니다 — 이 체크리스트는 단계를 넘어갈 때 확인합니다. 신규 표시는 이번 검토(G1~G6)에서 신설 제안한 항목입니다. 체크 상태는 저장되지 않습니다 (화면 점검용).
T1. 기획 → 이슈 등록 (기획 하네스)
T2. 이슈 → 착수 (Ready 전환 — 사람 게이트)
T3. 개발 → dev QA
T4. 발견 → 역반영 (분류 라우팅)
T5. 주기 운영 (루프 위생 — 주 1회 권장)
도입 권고와 관련 문서
공백 6건 중 무엇부터 메울지의 우선순위와, 이 가이드가 요약한 정본 문서 목록입니다.
우선순위 권고
- 1 G3 stale TC 검출 — 최우선. 공백 중 유일하게 "기획 의도와 다른 기준으로 검증이 통과"할 수 있는 구멍이라 자동화 루프의 신뢰를 직접 깎습니다. T5의 좌표 대조를 결정론 점검 절차로 구체화합니다.
- 2 G5 스위퍼 주기 확정. scan은 read-only라 주기 실행에 승인 부담이 없습니다. 주 1회로 시작.
- 3 G1 태그 수신 규칙의 계약 편입. 개발 하네스와의 협의 항목 — 편입 전까지는 T4의 무태그 위생 점검이 방어선입니다.
후속 과제 후보
- T5 좌표 대조(버전 좌표 목록 vs TC 표기)의 결정론 점검 절차 초안
- 체크리스트가 운영에서 검증되면 v1.0 승격 + 기획-이슈-협업-가이드에 링크 추가
- G2 리뷰 신선도 기준(재실행 트리거)의 수치 확정 — 운영 데이터 축적 후
관련 문서 (정본)
| 문서 | 관계 |
|---|---|
| docs/기획-개발하네스-경계.md ↗ | WHAT/HOW 경계 원칙과 강제 장치 4종 |
| docs/협업-역할-결정권-계약.md ↗ | 역할·결정권 상위 계약 |
| docs/기획 운영 계약.md ↗ | version·CHANGELOG 규칙 (§4.3), 코드 산출물 침범 방지 (§6) |
| docs/기획 자동화 운영 계약.md ↗ | 자동화 운영 상위 계약 |
| docs/guides/기획-이슈-협업-가이드 | 태그·버전·실물 예시 (사람용 요약) |
| .claude/skills/bs-plan-review/ | 이슈 등록 전 검토 게이트 (R0~R8) |
| .claude/skills/bs-planning-boundary/ | 기획 작성 시점 경계 스킬 |
| .claude/skills/bs-issue-comment/ | 이슈 본문·코멘트 작성 정본 (태그 5종) |
| .claude/skills/bs-plan-update/ | 기획 반영 · 버전 업 · 완료 좌표 마감 |
| .claude/skills/bs-plan-issue-sync/ | 일괄 수거 · 완료 SHA 검증 · QA handoff |
이 가이드는 요약본입니다 — 근거·세부 조항은 md 정본 ↗이 우선합니다.