git:20260827.80b4620 to git:20260907.ddbf343

- <!-- cck:begin rules-v1.4.0 sha256:0a03ad2f1a28364384d90ee69b684444ae5526623cde50c855c6120b44f9eca1 -->

- | `rules/code-quality` | 코드 품질 규범 — 호스트 무관 |

- | `rules/definition-of-done` | 완료 판정 규율 — 호스트 무관 |

- | `rules/feedback-loop` | 결함 학습 루프 — 호스트 무관 |

- | `rules/loop-engineering` | 루프/재시도 규율 — 호스트 무관 |

- | `rules/planning-check` | 계획 전 확인 규율 — 호스트 무관 |

- | `rules/planning-protocol` | 계획 수립 프로토콜 — 호스트 무관 |

- | `rules/ssot` | 단일 진실 원천 규범 — 호스트 무관 |

- | `rules/tool-usage-priority` | 도구 선택 우선순위 — 개념 수준에서 호스트 무관 |

- | `rules/agent-delegation-chain` | Claude Code 서브에이전트 호출·수명주기 규격에 종속 |

- | `rules/agent-system` | Claude Code 서브에이전트 정의 규격에 종속 |

- | `rules/mcp-usage` | Claude Code의 MCP 도구 allowlist 규격에 종속 |

- | `rules/parallel-worktree` | `isolation: worktree` 프론트매터(네이티브 프리미티브)에 종속 |

- | `rules/task-resume` | Claude Code Task 도구 수명주기에 종속 |

- ### Code Quality Rules

-

- #### Functions

-

- - ALWAYS keep functions under 20 lines, parameters under 3, nesting under 2 levels

- - NEVER write functions with 50+ lines, 5+ parameters, or 4+ levels of nesting

- - ALWAYS name functions to clearly express their role (`calculateTotalPrice`, `validateUserInput`)

- - NEVER use vague names: `calc`, `process`, `doStuff`, `handle`

- - ALWAYS apply single responsibility — one function does one thing

-

- ```typescript

- // DO: separate responsibilities

- function saveUser(user: User) { ... }

- function sendWelcomeEmail(email: string) { ... }

- function logUserCreation(userId: string) { ... }

- ```

-

- #### Error Handling

-

- - NEVER ignore errors or handle them with `console.log` only

- - ALWAYS handle each error type explicitly; rethrow unknown errors upward

- - ALWAYS preserve context when rethrowing: `throw new AppError({ code, message: \`...\${userId}\`, cause: error })`

-

- ```typescript

- } catch (error) {

- if (error instanceof NetworkError) return handleNetworkError(error);

- if (error instanceof ValidationError) return handleValidationError(error);

- throw error;

- }

- ```

-

- #### Conditionals

-

- - ALWAYS use early return instead of nested conditions

- - ALWAYS extract complex boolean expressions into named variables

-

- ```typescript

- if (!user) return null;

- if (!user.isActive) return null;

- if (!user.hasPermission) return null;

- return doProcess(user);

- ```

-

- #### Type Safety

-

- - NEVER use `any` — always use explicit types

- - NEVER overuse type assertions (`as`) — use type guards (`data is User`) instead

- - ALWAYS handle null: `user?.name ?? "Unknown"` — never skip null checks

- #### Testability

- - ALWAYS inject dependencies via constructor: `constructor(private db: IDatabase)`

- - NEVER hardcode `new Database()` inside a function

- - ALWAYS write pure functions: same input → same output, no side effects on global state

- ### Definition of Done — 완료 게이트 (Spec 6 / W-010)

-

- "완료/끝/통과"는 **판단이 아니라 명령의 출력**이다. verification-before-completion의

- 확장 — 코드뿐 아니라 **완료 주장 자체**를 게이트한다.

-

- #### Iron Law of Completion

-

- > "완료"를 주장하기 전:

- > 1. **그 프로젝트의 검증 명령**을 fresh run 한다 — 이 kit 레포에선

- > `scripts/verify-done.sh`, 다른 프로젝트에선 그에 해당하는 것(테스트·린트·빌드;

- > README/CI 설정에서 찾고, 없으면 사용자에게 확인). 스크립트가 없다는 사실이

- > 검증을 면제하지 않는다.

- > 2. 출력을 전부 읽는다.

- > 3. 기계 검사 FAIL이 하나라도 있으면 → "완료"라 하지 않는다. 실제 상태를 증거와 함께 보고.

- > 4. 수동 DoD 항목은 명시적으로 attest(체크)한다 — 건너뛰면 "완료" 아님.

- > **명령을 실행하지 않고 완료를 주장하는 것은 오류다.**

-

- #### 금지 어휘 규율

-

- 검증 전에는 "완료/끝났다/done/통과"를 쓰지 않는다. 대신 정확히 말한다:

- "구현 + self-validation 완료, 미결: [홀리스틱 검증 / 문서 sync / 통합]".

- "완료"라는 단어는 DoD 체크리스트가 전부 green일 때만 쓴다.

-

- #### Definition of Done (모든 Work 공통)

-

- ##### 기계 검사 (FAIL 시 완료 불가)

-

- 아래는 **이 kit 레포**의 게이트 항목이다(`scripts/verify-done.sh`가 강제). 다른

- 프로젝트에선 대응물로 치환한다 — 어느 프로젝트든 최소 **테스트 green · 린트 clean ·

- 시크릿 clean · 문서/버전 sync**는 남는다.

- - [ ] JSON 유효 (모든 plugin.json + hooks.json + marketplace.json)

- - [ ] plugin.json 필수 필드 + agent frontmatter + 금지 필드 (CI 동등)

- - [ ] ruff clean

- - [ ] pytest green

- - [ ] 시크릿 스캔 clean

- - [ ] 문서 카운트 sync (rules / skills 수가 문서 주장과 일치)

- - [ ] stale 참조 0 (삭제된 컴포넌트가 활성 참조로 남지 않음)

- ##### 수동 attest (사람/Claude이 증거와 함께 명시)

- - [ ] 스펙·계획의 모든 항목 구현 (누락 없음 — spec ↔ 코드 대조)

- - [ ] 적대적 리뷰 1회 (버그·엣지케이스·문서 sync 능동 탐색)

- - [ ] Work 라이프사이클 상태 정확히 보고 (active/validation vs completed, 통합 여부 명시)

- - [ ] CHANGELOG·README·CLAUDE.md 영향 반영

- #### 루프 종료 조건 (loop-engineering 연계)

- 배치 루프의 완료 조건 = **프로젝트 검증 게이트 green + 수동 DoD attest 완료 + Work 상태 해소**

- (이 레포에선 `scripts/verify-done.sh`).

- "마지막 스텝 도달"은 완료 조건이 아니다. (`rules/loop-engineering.md` 참조)

- **완료 보고·핸드오프·사용자 입력 대기로 턴을 끝내기 직전, `TaskList`를 조회해

- "작업이 실제로 끝났는데 마킹만 안 된" 태스크를 completed로 정리한다 — 마킹이 보고보다

- 먼저다. 진행 중/대기 태스크는 절대 마킹하지 않는다(잔존 사유를 보고에 명시).**

-

- - 근거: "마지막 태스크"는 내용이 대개 보고/마무리라서, 마킹을 보고 뒤에 두면 턴이

- 사용자 대기로 끝나며 완료 처리가 증발한다 (in_progress/pending 영구 잔존 — 실측된

- 반복 버그).

- - 스킬 체크리스트 태스크뿐 아니라 ad-hoc으로 만든 태스크에도 적용된다.

- - 미완 항목이 실제로 남았으면 completed로 위장하지 말고 잔존 사유를 보고에 명시한다

- (false-green 금지 — 정리 대상은 '끝났는데 마킹 안 된' 태스크뿐이다).

- ### Loop Engineering Rule (Spec 5 / W-009)

-

- **Harness Engineering**(어디서·무엇으로 행동하는가)의 상보 개념. Loop Engineering은

- **얼마나 오래·끈질기게** 행동하는가를 다룬다. 승인된 계획을 P0·완료·가드 도달 전까지

- 자율로 완주한다.

-

- #### 게이트 vs 루프 — 절대 혼동 금지

-

- | | 게이트 (설계) | 루프 (실행) |

- | --- | --- | --- |

- | 목적 | 사람 승인 — 무엇을 만들지 | 자율 완주 — 끝까지 어떻게 |

- | 멈춤 | **의도적 멈춤** (brainstorming/plan-task HARD-GATE) | **멈추지 않음** (P0·완료·가드 제외) |

- | 예 | 설계 승인, 스펙 검토 | auto-dev 배치 실행, Task dispatch |

- - 설계 게이트는 유지한다 — 루프가 게이트를 우회하지 않는다.

- - **게이트 통과 후에는** 매 단계 확인을 구하지 않는다. 승인된 배치는 완주한다.

- #### 실행 루프 드라이버 (네이티브/기존 인프라만)

- > `/goal`·`ultracode`는 대화형 전용이라 스킬에서 프로그래밍 트리거 불가(2026.6).

- > 따라서 드라이버는 검증된 Task 시스템 + 스킬 루프로 구성한다 (자체 데몬 없음).

- ```

- 승인된 배치 (여러 Work/Task)

- while (미완료 Work/Task 존재):

- 0. 재앵커: 대화 요약이 아닌 planning-results.md 원본을 다시 읽는다

- (장기 루프에서 요약은 열화·drift한다 — authority 원본이 기준).

- 1. TaskList → unblocked Task 선택

- 2. 실행 (dispatch / 직접 구현)

- 3. 완료 → checklist pass <id>(verify 통과) → progress.md 래칫 → TaskUpdate(completed)

- 4. 종료 가드 점검 (아래)

- 5. 다음 unblocked로 — 사람 확인 없이 전진

- → 완료 보고

- ```

- 루프는 **반드시** 아래에서 멈춘다:

-

- - **P0 도달**: 데이터/보안/결제/핵심로직 모호함 → 즉시 `AskUserQuestion`.

- - **완료**: 프로젝트 검증 게이트 green(이 레포: `scripts/verify-done.sh`) + 수동 DoD attest 완료 + 배치의 모든 Work/Task 상태 해소. "마지막 스텝 도달"은 완료가 아니다 (`rules/definition-of-done.md`).

- - **max_iterations**: 한 배치에서 진전 없는 반복이 상한(기본 동일 Task 2회/배치 누적 과다) 초과 → 사람 에스컬레이션.

- - **idle 감지 (커밋 기준)**: 최근 N iteration에서 새 커밋 0건이면 진전 없음으로 보고 종료

- (모델의 "작업 중" 주장이 아닌 git 커밋이라는 관찰 가능한 신호로 idle을 판정).

- - **루프 감지**: 동일 Task/에이전트가 진전 없이 2회+ → 중단 보고.

- - **검증 실패 잔존**: validation이 가드(continueOnBlock) 재시도 후에도 실패 → 보고.

-

- #### 적용

- - `auto-dev`: 배치 모드에서 한 Work 완료 시 다음 unblocked Work로 자동 전진(위 드라이버).

- - 단발 실행(`/auto-dev W-XXX` 단일)은 기존 동작 유지 — 루프는 배치에만.

- - opt-in·하위호환: 루프 실패가 본 작업을 막지 않는다.

- ### Planning Check Rules

-

- NEVER implement based on assumption. ALWAYS stop and verify specs first.

- #### 기획 확인이 필요한 상황

- 1. **요구사항 불명확**: "~할 것 같다", "보통은 ~" → 즉시 기획 문서 확인

- 2. **엣지 케이스**: 빈 값·오류·권한 없음 동작 → 기획서 확인, 없으면 사용자에게 질문

- 3. **다중 해석**: 표현이 모호한 요구사항 → 명확한 정의 확인

- 4. **비즈니스 로직**: 할인 계산·권한 체계·상태 전이 → 반드시 기획서/명세 기반 구현

- 1. 불확실성 감지 즉시 멈춤

- 2. `docs/planning/` → (설치돼 있으면) Notion·Figma MCP → GitHub Issues 순으로 검색.

- MCP가 없으면 건너뛴다 — 설치를 가정하지 않는다.

- 3. 정보 부재 시 AskUserQuestion으로 옵션 A/B 제시

- 4. 결정 내용과 근거를 코드 주석에 기록

-

- #### 질문 형식 (기획 부재 시)

-

- ```

- [기능명]에 대해 확인이 필요합니다.

- 상황: [현재 구현하려는 것]

- 불명확한 점: [구체적인 질문]

- 옵션: A) [해석 1] B) [해석 2]

- ```

-

- #### 체크리스트

-

- **구현 전:** 요구사항 문서 존재 / 성공·실패·로딩·빈 값 상태 정의 / 엣지 케이스 명시

-

- **구현 중:** NEVER guess / NEVER deviate from spec / NEVER add unspecified features

- **구현 후:** 구현 결과가 기획과 일치 / 모든 케이스가 기획대로 동작

- - **P0** — 데이터 무결성·보안·금융·핵심 비즈니스: **즉시 중단 + 질문**

- - **P1** — UX 분기·비즈니스 디테일: 기본값 적용 후 나중에 확인

- - **P2** — UI 디테일·엣지케이스: TODO 기록

- - **P3** — 기술 선택(라이브러리·패턴): 자율 판단

-

- #### Dev → Planning 역위임 프로토콜

-

- 구현 중 기획 모호함 발견 시 아래 유형으로 분류하고 Planning으로 돌아간다:

-

- - `P0_AMBIGUITY` — AskUserQuestion으로 사용자 확인

- - `MISSING_SPEC` — 해당 명세 추가 (여정/규칙)

- - `INFEASIBLE` — 대안 검토 후 사용자에게 보고

-

- #### 작업 규모 판단

-

- - **Small**: 1개 모듈·1-3파일·~10h → 요구사항만

- - **Medium**: 2-3개 모듈·4-10파일·20-50h → +사용자 여정

- - **Large**: 4개+ 모듈·10파일+·50h+ → +비즈니스 로직

-

- #### Planning 완료 조건

-

- ALWAYS ensure before handing off to Dev:

-

- - P0 모호함 = 0

- - 핵심 요구사항 정의·영향 범위 식별·리스크 분석 완료

- - Medium+: 사용자 여정·주요 상태 전이·에러 처리 전략 포함

- - Large+: 비즈니스 규칙·규칙 간 관계·예외 처리 포함

-

- #### P0 질문 형식

-

- P0 발견 시: 즉시 중단 → AskUserQuestion → 답변 기록 → Planning 재진행

-

- ```

- **맥락**: [상황] **질문**: [구체적 질문]

- **옵션**: 1. [A] 2. [B]

- ```

-

- #### 정보 전달 형식

-

- **Planning → Dev:** 요구사항 요약 / 확인된 사항 / 사용자 여정(해당시) / 비즈니스 규칙(해당시) / 미결정 P1/P2 / 구현 권장사항

- **Dev → Planning:** 유형(P0_AMBIGUITY|MISSING_SPEC|INFEASIBLE) / 발생 컨텍스트 / 발견한 문제 / 제안 옵션 / 필요한 결정

- #### 모호함 감지

- NEVER use language: "~할 것 같다", "아마 ~", "보통은 ~", "임시로 ~"

- ALWAYS use: "기획에 따르면", "사용자가 요청한", "확인 결과"

- ### SSOT (Single Source of Truth) Rules

-

- #### Core Principles

-

- - ALWAYS define error types, API endpoints, and env vars in exactly one file

- - NEVER copy values — always reference via import: `import { API_URL } from "@/config/env"`

- - ALWAYS structure code so one change propagates everywhere — if one change requires editing 10 files, that is an SSOT violation

-

- #### Error Logging

-

- - ALWAYS route all errors through a single central handler

- - ALWAYS include these fields in every error log: `code` (e.g. AUTH_001), `message`, `timestamp` (ISO 8601), `severity` (debug → critical)

- - NEVER scatter error handling logic across multiple modules

- ```

- src/infrastructure/errors/

- ├── types.ts # error codes + AppError interface

- ├── messages.ts # error message constants

- ├── handler.ts # central handler (normalizeError + notifyOnCall)

- └── logger.ts # structured logger

- ```

- #### SSOT Checklist

- - Is this value already defined somewhere else? → reference it, don't redefine

- - Is this a hardcoded string/number that should be a named constant? → extract it

- - Does this error go through the central handler? → if not, fix it

- - Does changing this require editing multiple files? → SSOT violation signal

- - Does the same bug appear in multiple places? → duplicate code signal

- <!-- source: rules/tool-usage-priority.md (원문 그대로) -->

- ### Tool Usage Priority Rules

- #### File Operations

- NEVER use Bash for file operations. ALWAYS use the dedicated tool:

- - Read files → **Read** (NOT cat/head/tail)

- - Edit files → **Edit** (NOT sed/awk)

- - Create files → **Write** (NOT echo>/cat<<EOF)

- - Search files → **Glob** (NOT find/ls)

- - Search content → **Grep** (NOT grep/rg)

- #### Bash Allowed Cases

- DO use Bash for: git, package managers (npm/pip/brew), services (docker/systemctl), builds (make/cargo/go), DB CLIs (psql/mysql/redis-cli), system ops (chmod/chown/ln/mkdir), process management (kill/ps/lsof).