64 lines
5.5 KiB
Markdown
64 lines
5.5 KiB
Markdown
---
|
||
name: build-loop
|
||
description: Use when doing ANY code implementation work (feature, bugfix, refactor, ops/config change, docs-in-code) — the explicit inspect→plan→implement→verify loop that makes real code work actually get done well, instead of narrating frameworks (TDD/12-Factor/SLO) and stopping at a thin report. Scales the paperwork gate to risk/tier so a one-line bugfix is not falsely Blocked on a full PRD/API-contract/data-model/threat-model.
|
||
---
|
||
|
||
# Build Loop — 코드를 '잘' 끝내는 실행 루프
|
||
|
||
## 왜 이 스킬이 필요한가 (핵심 진단)
|
||
|
||
프레임워크를 나열하는 것(TDD·12-Factor·SLO·DORA)은 코드를 끝내지 못한다. 실제 결함(#8): 에이전트가
|
||
프레임워크 이름만 설명하고 **얇은 report 한 줄로 끝**낸다. 그리고 모든 빌드가 PRD+API계약+데이터모델+
|
||
위협모델을 **일괄** 요구해서, 한 줄짜리 버그픽스마저 규칙상 Blocked가 된다 — 모델이 규칙을 무시해야만 일이 된다.
|
||
|
||
> **불변식: 루프가 척추, 프레임워크는 각 단계를 '잘' 하는 법.** 그리고 **문서 게이트는 위험도에 비례**한다(일괄 아님).
|
||
|
||
## 구현 루프 (7단계 — 모든 코드 작업의 기본 절차)
|
||
|
||
순서를 지켜라. 코드를 만지기 전에 먼저 본다.
|
||
|
||
1. **inspect** — 현재 동작을 **재현**한다(버그면 실패를, 기능이면 현 상태를). 기존 코드·컨벤션·**호출부(callers)**·
|
||
인접 테스트를 읽어 변경이 무엇을 건드리는지 파악한다. *탐색 없이 바로 코딩 금지.*
|
||
2. **smallest safe change plan** — 목표를 만족하는 **가장 작고 안전한** 변경으로 좁힌다. 무엇을 바꾸고 무엇을
|
||
**안 바꿀지**(non-goals), 되돌리기(rollback) 방법을 정한다. 큰 표면·비가역이면 여기서 설계 게이트로 승격한다(아래).
|
||
3. **implement** — 계획대로 구현한다. 기존 컨벤션·패턴을 따르고, 스코프를 넘는 리팩터를 끼워넣지 않는다.
|
||
4. **targeted verify** — 변경한 바로 그 동작을 검증한다. **합리적이면 실패하는 테스트/재현을 먼저** 만들고(그 다음
|
||
통과), 재현 스크립트로 before→after를 실증한다.
|
||
5. **broader verify** — 회귀를 본다: lint · typecheck · unit · (해당되면) integration. 실행 명령과 결과를 남긴다.
|
||
6. **inspect own diff** — 자기 diff를 다시 읽는다: 디버그 잔여물·비밀·범위이탈·누락 케이스·주석/문서 갱신 여부.
|
||
7. **report** — report-header(BLUF)로 낸다. **무엇을 검증했는지 vs 무엇을 실행하지 않았는지**를 정직하게 구분해
|
||
명시한다(근거 없는 '통과' 금지). 실물은 primary-artifacts로, 보고서는 그 envelope.
|
||
|
||
프레임워크는 이 루프를 **대체하지 않는다**: TDD=4단계의 방법, 12-Factor=3단계의 구성 규율, SLI/SLO·관측성=
|
||
5단계 이후 운영 검증, contract-first(OpenAPI)=표면을 새로 만들 때 2단계에서 계약을 먼저 고정.
|
||
|
||
## 문서 게이트를 위험도에 비례시켜라 (paperwork ∝ risk/tier)
|
||
|
||
모든 빌드에 PRD/API계약/데이터모델/위협모델을 **일괄** 요구하지 마라. 변경을 먼저 분류한다
|
||
(governance-tiers `risk-classification-rubric`: risk × reversibility × blast-radius):
|
||
|
||
- **light path — 단순 변경**(버그픽스·문서·설정/ops·작은 수정; risk Low · two-way-door · single-role → tier light):
|
||
선행 설계 문서 **불요**. 필요한 최소 접지 = ①현재 동작/재현 ②smallest-safe-change 계획 ③검증(테스트/재현 receipt).
|
||
루프 7단계를 그대로 돌리되 무거운 산출물은 만들지 않는다.
|
||
- **substantial path — 새 표면/실질 변경**(새 공개 API·스키마/데이터모델 신설·교차팀 blast·보안/프라이버시/법무 접촉·
|
||
one-way-door → tier standard/heavy): **"설계 Accepted 후 구현"** 규칙 유지. `collaboration-map` design-to-build-contract의
|
||
must-read-designs(PRD/RFC·ADR/api-contract/data-model, 보안 접촉 시 threat-model)가 Accepted인지 확인하고,
|
||
없으면 임시 우회 대신 **BlockedReport**로 설계로 되돌린다. tier=heavy는 plan-signoff(사람 승인) 전 실행 금지.
|
||
|
||
경계 판단(둘 중 하나라도 해당이면 substantial로 승격): 새 공개 계약/표면 · 데이터 모델 변경 · 마이그레이션/비가역 ·
|
||
보안·PII·법무 접촉 · 프로덕션/고객/매출 blast · 교차팀 영향.
|
||
|
||
## Self-check (report 직전 필수)
|
||
|
||
- [ ] 코딩 전에 **inspect**(재현+호출부)를 실제로 했나? 아니면 추측으로 고쳤나.
|
||
- [ ] 변경이 **가장 작고 안전한** 형태인가? 스코프를 넘는 리팩터를 끼웠나.
|
||
- [ ] targeted verify가 있나(합리적이면 실패 테스트/재현 먼저)? broader verify(lint/typecheck/unit)를 돌렸나.
|
||
- [ ] report가 **검증한 것 vs 실행 안 한 것**을 정직히 구분하나? 근거 없는 '통과'가 아닌가.
|
||
- [ ] 이 변경이 light인가 substantial인가 — 게이트를 위험도에 맞게 적용했나(과잉 차단도, 과소 검증도 아님).
|
||
|
||
## 근거 (E3)
|
||
- systematic debugging(재현 먼저): 재현 없는 수정은 추측이다 — reproduce → isolate → fix → verify.
|
||
- test-driven development(실패 테스트 먼저): red→green→refactor로 동작을 고정.
|
||
- Design Doc/ADR는 **비자명·새 표면** 작업에서 먼저(일괄 아님): https://www.industrialempathy.com/posts/design-docs-at-google/
|
||
- proportional governance(위험도 비례 게이트): governance-tiers.yaml `risk-classification-rubric`.
|