crumbs-spec 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sienna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,397 @@
+# crumbs-spec 🍞
+
+**한국어** · [English](README.md)
+
+[![CI](https://github.com/Sienna94/crumbs-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/Sienna94/crumbs-spec/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/crumbs-spec)](https://www.npmjs.com/package/crumbs-spec)
+
+에이전트가 길을 잃지 않게 문서마다 빵부스러기(링크)를 남기고, 인덱스에서 상세 문서까지 한 길로 이어지는 **살아 있는 스펙**을 만들어요. 저장소가 *지금* 어떻게 동작하는지를 책임 단위 문서로 두고, 그 문서들이 잘 이어져 있는지 명령 하나로 검사하고, 에이전트가 문서를 쓰고·찾고·묻고·반영하는 절차를 스킬로 고정한 도구예요.
+
+## 왜 만들었나요
+
+실제 앱 저장소에서 수십 개의 스펙 문서를 에이전트와 함께 운영하다 보니 같은 일이 자꾸 반복됐어요.
+
+1. 스펙이 변경 단위(기능별 `spec.md`, 티켓)로만 남아서, 몇 달 뒤 "지금 이 규칙이 뭐지?"에 답할 문서가 없었어요.
+2. 위키처럼 쌓으니 같은 규칙이 여러 문서에 조금씩 다르게 적혔고, 어느 쪽이 맞는지 아무도 몰랐어요. 나중에 벤치마크를 돌려 보니 에이전트가 문서 간 불일치를 셋이나 찾아냈어요.
+3. 에이전트가 문서를 읽을 때 폴더 구조와 검색에 기대다 보니 다른 영역으로 새거나 grep으로 떨어졌어요. 질문 하나에 문서 8개를 읽는 일도 있었고요.
+
+"문서를 더 잘 쓰자"로는 해결이 안 됐어요. **구조를 기계가 강제하는 도구**가 필요했어요. 정책의 소유자를 하나로 정하고, 링크 그래프를 검사하고, 모르는 것은 질문으로 남기게 하면 에이전트도 사람도 같은 길로 문서에 닿아요. 그래서 빵부스러기를 뿌리기 시작했어요.
+
+## 다른 도구와 어떻게 다른가요
+
+Spec Kit은 구현 전 계획을, LLM Wiki는 자료를 쌓는 위키를 잘 다뤄요. crumbs-spec은 그 사이의 빈자리, **구현이 끝난 뒤에도 남아야 하는 현재 상태**를 맡아요. 대체가 아니라 보완 관계예요.
+
+| | GitHub Spec Kit | OpenSpec | Karpathy LLM Wiki | **crumbs-spec** |
+|---|---|---|---|---|
+| 문서 단위 | 변경(기능) 하나: `spec.md`·`plan.md`·`tasks.md` | 현재 상태 스펙 + 변경 델타 | 엔티티·개념·원본 요약 페이지 | **책임(사용자 흐름) 하나**. 정책은 문서 하나가 소유 |
+| 시점 | 구현 전 | 구현 전·후 | 자료 반영 시점 | **구현 뒤 현재 동작** |
+| 기존 코드 | "추론하지 않는다"고 스스로 밝힘 | 온보딩은 있으나 코드→스펙 초안은 없음 | 원본 자료가 대상, 코드 아님 | **crumbs-writer 스킬이 코드·테스트에서 초안을 만들고, 모르는 것은 `[확인 필요]` 질문으로 남겨요** |
+| 탐색 | 폴더와 파일 이름 | 폴더와 파일 이름 | 인덱스 우선 | **인덱스 → 개요 → 상세 링크만**. ID·front matter 없음 |
+| 기계 검사 | spec·plan·tasks 일관성 | `openspec validate`(구조) 검사와 아카이브 시 델타 병합 | 고아 페이지·끊긴 링크 lint(LLM 판단 포함) | **결정론적 16개 구조 규칙**: 링크·앵커·도달 가능·역링크·정책 이름 중복·근거 경로·절 순서·흐름 도식·로그 형식·닫히지 않은 주석 |
+| 구현 후 동기화 | 팀이 유지 방식을 고름 | `archive`/`sync`로 변경분만 | 질의 결과를 위키에 환류 | **에이전트 규칙("요청 없어도 같은 변경에서 문서 갱신")과 결정 로그** |
+| 사람 가독성 | 산문 | 산문 | 산문 | **흐름 도식(Mermaid)과 분기 표를 템플릿에 포함** |
+
+Kiro 스펙과 BMAD는 Spec Kit과 비슷하게 기능 단위이고 구현 전에 쓰이므로 따로 싣지 않았어요. 한국어 기획 문서가 다섯 가지를 모두 비교해요.
+
+LLM Wiki에서는 원본/위키/스키마 분리, 인덱스 우선, 추가 전용 로그, 사람이 감독하는 ingest를 그대로 가져왔어요. 일부러 다르게 한 건 셋이에요. 엔티티 페이지 대신 책임 단위로 조직하고(여러 흐름이 분기 축으로 쓰는 개념만 `concepts/`에 둬요), 문서는 에이전트가 유지하되 사람이 소유하고, lint는 LLM 판단 없이 결정론적으로만 해요. 더 자세한 비교는 [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) 1절에 있어요.
+
+## 중요하게 생각한 것
+
+- **현재 상태의 단일 진실.** 변경 디렉터리를 만들지 않아요. 문서는 "무엇이 바뀌었나"가 아니라 "지금 어떻게 동작하나"를 설명해요.
+- **추측 금지.** 코드·테스트·승인된 자료로 확인되지 않은 규칙은 "지금은 이렇게 동작한다" 서술과 `[확인 필요]` 질문으로만 남겨요. `check`는 질문이 남은 문서마다 `open-question` 경고를 하나씩 내요. 어떤 서술이 추측인지는 스킬 규칙과 리뷰어의 몫이고, `check`는 판별하지 못해요.
+- **정책 하나에 주인 하나, 이름 단위로 검사.** `check`는 같은 정책 이름이 두 문서에 있거나 한 문서에 두 번 있으면 거부해요. 다른 이름으로 같은 말을 하는 두 정책은 찾지 못하고, 그 이름 규칙은 writer 스킬이 맡아요.
+- **사람 우선의 본문.** ID, 상태 표, 문법 강제가 없어요. 탐색 정보는 링크와 제목에만 둬요.
+- **검사는 결정론적으로, 판단은 사람과 스킬이.** `check`는 구조만 봐요. 문체·내용·노후 판정은 스킬 지침과 사람이 맡아요.
+- **결정은 한 곳에.** 질문이 답을 얻으면 로그에 `decision` 항목을 남기고 문서는 날짜 링크 하나로 그 결정을 가리켜요.
+- **두 언어.** `crumbs.json`의 `lang`이 저장소 전체의 템플릿, 스킬, 메시지, AGENTS 블록 언어를 정해요. 기본값은 영어(`en`)이고 `ko`를 쓰면 한국어가 돼요.
+
+## 실제로 써 보니 (한 번 실행, 자체 보고)
+
+이 결과는 벤치마크가 아니라 일화로 읽어 주세요. 질문 18개로 한 번 돌린 결과이고 작성자가 채점했어요. 질문은 기존 스펙 체계에서 가져왔고, 두 대상의 규모도 달라요(문서 38개 대 약 127개). 원본 데이터는 비공개 저장소에서 나와 공개할 수 없어요. 로드맵의 예제 앱과 벤치마크 러너가 이 결과를 대신하기 위한 것이에요.
+
+실제 앱 저장소 세 영역(코드 약 4만 줄)을 기존 스펙 문서를 전혀 보여 주지 않고 crumbs-writer 스킬로 다시 썼어요. 그다음 기존 스펙 체계와 crumbs 체계에 같은 질문 18개를 던져 에이전트가 문서만 읽고 답하게 했어요.
+
+**제로 베이스에서 쓰는 데 든 비용** (에이전트 1개가 도메인 하나를 맡음, 병렬 3개)
+
+| 도메인 | 코드 범위 | 만든 문서 | 정책 (확정 / 미해결 질문) | 에이전트 토큰 | 작성 시간 |
+|---|---|---|---|---|---|
+| 결제 | 약 2만 줄 | 19개 | 100 (5 / 95) | 57만 | 1시간 7분 |
+| 뷰어 | 약 2만 3천 줄 | 40개 | 194 (29 / 165) | 85만 | 1시간 7분 |
+| 인증 | 약 1만 줄 | 35개 | 195 (64 / 131) | 79만 | 1시간 13분 |
+
+작성 시간은 에이전트 전사의 타임스탬프에서 10분 넘게 비어 있던 대기 시간을 뺀 실제 작업 시간이에요. 세 도메인을 병렬로 돌려 1시간 15분쯤에 모두 끝났어요. 작성자가 결과를 직접 검토했을 때 지어낸 정책은 없었고, 기존 스펙과 코드가 달랐던 6곳은 코드대로 적었어요. 이 검토는 작성자가 했고 독립적으로 하지 않았어요. 그 뒤 사용자 흐름 단위로 다시 묶어 38개 문서가 됐어요.
+
+**같은 질문 18개로 비교한 탐색 비용** (에이전트는 문서만 읽고 코드는 금지)
+
+정답 수는 crumbs가 적었지만(18개 중 15개 대 17개), 읽은 파일과 토큰은 더 적었어요.
+
+| | 기존 스펙 체계 | crumbs-spec |
+|---|---|---|
+| 정답 | 17 / 18 (부분 1) | 15 / 18 (부분 3) |
+| 읽은 파일 수 합계 | 70 (평균 3.9, 최대 8) | 64 (평균 3.6, 최대 6) |
+| 검색(grep)으로 떨어진 횟수 | 3 | 1 |
+| 토큰 합계 | 232만 | 189만 (−18%) |
+
+기존 체계의 부분 정답은 소유 문서를 못 찾은 경우였고, crumbs의 부분 정답 3개는 모두 문서엔 3~5파일로 도달했는데 writer가 화면 수치·채널 분기 같은 세부를 버린 경우였어요. 그 원인에 대해 스킬 규칙("조건이 붙은 값은 버리지 않는다")을 추가했어요. 벤치마크는 다시 돌리지 않았어요. 질문이 기존 스펙에서 나와 기존 체계에 유리한 편향이 있다는 점은 감안해 주세요.
+
+## 설치와 빠른 시작
+
+Node.js 20 이상이 필요하고 실행 의존성은 없어요.
+
+```bash
+npx crumbs-spec init --skills all   # 문서 구조 + 에이전트 스킬 4종
+npx crumbs-spec init                # 문서 구조만
+npx crumbs-spec check               # 링크 그래프와 구조 검사
+```
+
+한국어 저장소는 `--lang ko`를 붙여요.
+
+`init`은 다음 파일을 만들고, 이미 있는 파일은 절대 덮어쓰지 않아요. `--skills all`이면 SKILL.md 여덟 개도 함께 써요. AGENTS.md에서는 `<!-- crumbs:start -->`와 `<!-- crumbs:end -->` 사이의 자기 블록만 바꿔요.
+
+```
+crumbs.json                      설정
+docs/specs/index.md              인덱스(입구)
+docs/specs/log.md                추가 전용 로그
+docs/specs/templates/overview.md 개요 템플릿
+docs/specs/templates/detail.md   상세 템플릿
+docs/raw/README.md               원본 자료 디렉터리(읽기 전용)
+AGENTS.md                        crumbs 블록(에이전트 규칙)
+```
+
+`crumbs.json`이 이미 있으면 `init`은 그 설정을 그대로 두고 `--spec-dir`와 `--lang`은 무시해요(그렇다고 알려 줘요). `init`의 마지막 줄은 다음에 실행할 명령이에요: `npx crumbs-spec check`.
+
+npm에 [`crumbs-spec`](https://www.npmjs.com/package/crumbs-spec)으로 올라가 있어요. 저장소를 클론해서 쓰려면 `npm run build` 뒤 `node dist/src/cli.js <명령>`으로 실행해요.
+
+## 기존 프로젝트에 추가하기
+
+이미 코드와 문서가 있는 저장소에 넣는 순서예요. 한 번에 다 옮기지 말고 도메인 하나부터 시작해요.
+
+1. **저장소 루트에서 `init`을 실행해요.** 스펙 루트가 따로 있으면 `--spec-dir`로 지정해요(예: `docs/crumbs`). 기존 파일은 건드리지 않고, `AGENTS.md`가 이미 있으면 `<!-- crumbs:start -->`와 `<!-- crumbs:end -->` 사이 블록만 끼워 넣어요.
+
+   ```bash
+   npx crumbs-spec init --spec-dir docs/crumbs --skills claude
+   ```
+
+2. **에이전트가 규칙을 읽게 해요.** Claude Code는 `CLAUDE.md`에 `@AGENTS.md` 한 줄이 있어야 crumbs 블록을 읽어요. 스킬은 `.claude/skills/`(Claude Code)와 `.agents/skills/`(Codex)에서 자동으로 찾아요.
+
+3. **기존 문서는 옮기지 않아요.** writer는 코드와 테스트만 원본으로 삼고, 기존 위키·설계 메모·README는 사용자가 원본 자료로 지목하지 않는 한 읽지 않아요. 지금 코드와 맞는지 확인할 수 없기 때문이에요. 기존 문서 중 근거로 쓸 것(기획서, 계약서, 정책 결정 기록)은 `docs/raw/`에 복사해 두고 `crumbs-ingest`로 한 건씩 반영해요.
+
+4. **첫 도메인을 코드에서 써요.** 가장 자주 질문받는 영역 하나를 고르고 writer의 "기존 코드 문서화" 모드로 맡겨요. 결과물의 `[확인 필요]` 질문 목록이 그 영역에서 사람이 결정해야 할 것의 목록이 돼요.
+
+   ```
+   src/billing/ 아래 코드를 crumbs-writer의 "기존 코드 문서화" 모드로 문서화해 줘.
+   도메인 디렉터리는 docs/crumbs/billing/이다. 확인하지 못한 정책은 질문으로 남기고 끝까지 해 줘.
+   ```
+
+5. **`check`를 CI에 걸어요.** 오류(끊어진 링크·앵커, 도달 불가 문서, 빠진 역링크, 없는 코드 경로, 정책 이름 중복)만 실패시키고 경고는 무시해요. 스펙 루트 안의 Markdown 가운데 아직 crumbs 문서가 아닌 것은 `crumbs.json`의 `exclude`에 넣어요. 항목은 스펙 루트 기준 상대 경로이고, `/`로 끝나면 그 디렉터리를 제외해요. 글롭 패턴은 없어요. 필수 절이 하나도 없는 문서는 `check`가 알려 줘요.
+
+6. **코드를 바꿀 때 문서를 같이 바꿔요.** AGENTS 블록이 "요청이 없어도 같은 변경에서 소유 문서를 갱신한다"를 에이전트에게 요구하니까, PR마다 `check`와 로그 항목이 함께 들어와요. 도메인이 하나씩 늘어나면서 인덱스가 채워져요.
+
+기존 스펙 체계가 있다면 두 체계에 같은 질문을 던져 비교해 보세요. 읽은 파일 수와 정답률로 어느 쪽이 더 잘 찾히는지 바로 보여요.
+
+## 스펙이 만들어지는 순서
+
+writer 스킬이 "기존 코드 문서화" 모드로 일할 때의 순서예요. "변경 반영" 모드는 1~2단계가 "바뀐 코드 경로를 근거에 적은 소유 문서 찾기"로 바뀌고 나머지는 같아요.
+
+```mermaid
+flowchart TD
+    A["인덱스와 템플릿 읽기"] --> B["진입점부터 코드와 테스트 따라 읽기"]
+    B --> C["책임 경계 정하기 사용자 흐름 하나 = 문서 하나"]
+    C --> D["현재 동작 쓰기 단계는 ### 소제목"]
+    D --> E{"테스트가 확정하는 규칙인가"}
+    E -->|예| F["정책으로 적기"]
+    E -->|아니오| G["지금 동작 서술 + 확인 필요 질문"]
+    F --> H["흐름 도식과 분기 표"]
+    G --> H
+    H --> I["근거 경로와 관련 문서 양방향 링크"]
+    I --> J["개요 문서 목록과 인덱스 갱신"]
+    J --> K["crumbs check"]
+    K -->|오류| I
+    K -->|통과| L["log add 결과 이유 문서"]
+```
+
+답이 생기면 `crumbs-interview`가 만든 질문에 사람이 답하고, writer가 질문 정책을 확정 정책으로 바꾸며 `decision` 로그와 결정 링크를 남겨요. 새 자료가 들어오면 `crumbs-ingest`가 영향 문서를 찾아 확인받은 뒤 반영해요.
+
+## 문서 모델
+
+역할은 넷이에요. 탐색은 항상 인덱스에서 시작해요.
+
+```
+docs/specs/index.md              인덱스: 도메인 목록 + 로그 링크
+docs/specs/<도메인>/overview.md   개요: 범위, 흐름도, 문서 목록, 용어
+docs/specs/<도메인>/<책임>.md     상세: 사용자 흐름 하나
+docs/specs/log.md                로그: 한 일을 시간순으로
+docs/specs/concepts/             여러 도메인이 함께 쓰는 개념(선택)
+docs/raw/                        계약서·기획 메모 같은 불변 원본
+```
+
+상세 문서의 절은 고정이에요.
+
+| 절 | 내용 |
+|---|---|
+| 목적 | 이 문서가 소유하는 책임 하나와 맡지 않는 범위 |
+| 현재 동작 | 사용자가 겪는 대로, 현재형으로. 단계가 셋 이상이면 `###` 소제목 |
+| 흐름 | 두 단계 이상이면 Mermaid 도식, 비교 축이 둘 이상이면 표 |
+| 정책 | `### 정책 이름`(저장소 전체에서 유일)과 규칙. 미확정이면 지금 동작 서술 뒤에 `[확인 필요]` 질문 |
+| 근거 | `/`가 들어간 백틱 경로와 설명. `check`가 경로의 존재를 확인해요 |
+| 확인 필요 사항 | `- [확인 필요] [정책 이름](#앵커) — 질문` |
+| 관련 문서 | 개요로 가는 링크와 이웃 문서. 역링크는 상호여야 해요 |
+
+예시(`docs/specs/shopping/장바구니.md`):
+
+````markdown
+# 장바구니
+<!-- ../index.md를 먼저 읽는다. 이 문서를 바꾼 뒤 ../log.md에 항목을 추가한다 -->
+
+## 목적
+사용자가 상품을 담고 수량을 바꾸고 비울 때까지의 흐름을 맡는다. 쿠폰 적용은 [쿠폰 할인](쿠폰-할인.md)이 맡는다.
+
+## 현재 동작
+- 사용자가 같은 상품을 다시 담으면 앱은 수량을 더한다.
+- 수량이 99를 넘으면 앱은 "최대 99개까지 담을 수 있습니다." 안내를 보이고 담지 않는다.
+
+## 흐름
+```mermaid
+flowchart TD
+    A["상품 담기"] --> B{"같은 상품이 있나"}
+    B -->|예| C["수량 합산"]
+    B -->|아니오| D["새 줄 추가"]
+    C --> E{"99 초과"}
+    E -->|예| F["안내 후 담지 않음"]
+```
+
+## 정책
+### 수량 상한
+장바구니 한 줄의 수량은 99 이하다.
+
+### 최소 주문 금액
+지금은 합계가 10,000원 미만이면 결제 버튼을 비활성화한다.
+[확인 필요] 10,000원이라는 기준의 근거는 무엇인가?
+
+## 근거
+- `src/cart/cart.ts:12-48` — 담기와 수량 합산
+- `test/cart/cart.test.ts` — 수량 상한
+
+## 확인 필요 사항
+- [확인 필요] [최소 주문 금액](#최소-주문-금액) — 10,000원이라는 기준의 근거는 무엇인가?
+
+## 관련 문서
+- [쇼핑 개요](overview.md)
+- [쿠폰 할인](쿠폰-할인.md)
+````
+
+문서 본문은 간결한 `-한다`체로 써요. 개요의 `## 용어`는 별칭을 소유 정책으로 잇는 링크 목록이에요(`- 정액권(정액제) — [정액권 이용 중 판정](정액권.md#정액권-이용-중-판정)`). 정의만 있는 용어는 여기서 끝나고, 여러 흐름이 분기 축으로 쓰는 개념(채널, 재화, 회원 상태)만 `concepts/`에 소유 문서를 둬요.
+
+## 명령
+
+```bash
+npx crumbs-spec init [--spec-dir <dir>] [--lang <en|ko>] [--skills <claude|codex|all>]
+npx crumbs-spec check [--format text|json] [--config <path>]
+npx crumbs-spec log add --kind <ingest|query|lint|drift|change|decision> "<제목>" [--body "<본문>"]
+```
+
+공통 옵션은 `--root <dir>`(저장소 루트, 기본값은 현재 디렉터리), `--lang <en|ko>`(init이 쓸 언어, 설정을 읽기 전 오류의 언어, 기본값 `en`), `-h`/`--help`, `-v`/`--version`이에요. 설정은 저장소 루트의 `crumbs.json`에 둬요(`specDir`, `index`, `overview`, `log`, `lang`, `headings`, `exclude`, `codeRoot`, `rawDir`).
+
+`check`의 출력은 `파일:줄 심각도 규칙: 메시지` 한 줄씩이고 마지막 줄이 요약이에요.
+
+```
+docs/specs/shopping/장바구니.md:34 error broken-anchor: 앵커가 없음: 쿠폰-할인.md#적용-순서
+docs/specs/shopping/장바구니.md:20 warning open-question: 미해결 질문 1개
+
+crumbs check: 문서 4개, 오류 1개, 경고 1개
+```
+
+**지원하는 Markdown.** 제목은 ATX(`#`부터 `######`까지)만 인식하고 setext 제목(밑줄식)은 인식하지 않아요. 인라인 링크와 참조 링크(`[텍스트][라벨]`, `[라벨][]`와 `[라벨]: 경로` 정의)를 검사해요. `[라벨]`만 쓴 축약 참조는 링크가 아니에요. 제목 앵커는 github-slugger 방식이에요. 공백마다 `-`가 되고, `-`와 `_`를 뺀 문장부호는 지우며, 연속된 `-`는 합치지 않아요. 예를 들어 `### 수량 & 한도`는 `#수량--한도`가 돼요. 스펙 루트 아래의 심볼릭 링크 파일과 디렉터리도 따라가요. 근거 경로에는 `/`가 있어야 하며 저장소 루트의 파일은 `./package.json`처럼 써요. `:12`, `:12-48`, `:12:5`, `:12-48,60-70` 같은 줄 표기를 받아요. `exclude` 항목은 스펙 루트 기준 상대 경로이고, `/`로 끝나면 그 디렉터리를 제외해요. JSON 출력의 모든 항목에는 `line`이 있어요(더 나은 위치가 없으면 1).
+
+### 검사 규칙
+
+| 규칙 | 심각도 | 잡는 것 |
+|---|---|---|
+| `index-missing` | 오류 | 인덱스 문서가 없어요(다른 규칙은 돌지 않아요) |
+| `missing-title` | 오류 | 첫 제목이 H1이 아니에요 |
+| `broken-link` | 오류 | 링크 대상 파일이 없거나, 철자(대소문자·유니코드 정규화)가 디스크의 파일과 달라요 |
+| `broken-anchor` | 오류 | 링크가 가리키는 제목(앵커)이 없어요 |
+| `unreachable` | 오류 | 인덱스에서 링크로 닿을 수 없는 문서예요 |
+| `missing-section` | 오류 | 역할별 필수 절이 없어요 |
+| `missing-backlink` | 오류 | 부모(개요·인덱스)로 돌아가는 링크가 없거나, 상세 A→B 링크에 B→A가 없어요 |
+| `missing-code-path` | 오류 | 근거의 코드 경로가 존재하지 않아요 |
+| `duplicate-policy` | 오류 | 같은 정책 이름이 두 문서에 있거나 한 문서에 두 번 있어요 |
+| `log-format` | 오류 | 로그 항목이 `## [YYYY-MM-DD] kind \| 제목` 형식이 아니거나, 날짜가 하루를 넘어 미래예요 |
+| `unterminated-comment` | 오류 | HTML 주석이 열린 뒤 닫히지 않아, 그 뒤의 문서 전체가 가려져요 |
+| `open-question` | 경고 | 질문이 남은 문서마다 경고 하나예요. 개수는 미해결 질문 수예요 |
+| `log-order` | 경고 | 로그 날짜가 역순이에요 |
+| `missing-flow` | 경고 | 현재 동작이 6단계 이상인데 도식도 표도 없어요 |
+| `section-order` | 경고 | 절 순서가 템플릿과 달라요 |
+| `log-body` | 경고 | `decision` 항목에 문서 링크가 없어요 |
+
+## 로그
+
+로그는 한 곳(`docs/specs/log.md`)에 시간순으로 덧붙여요. 제목은 작업명이 아니라 **사용자 결과 한 문장**이고, 본문은 세 줄이에요.
+
+```bash
+npx crumbs-spec log add --kind change "장바구니 수량 상한을 99로 올림" \
+  --body "결과: 한 줄에 99개까지 담을 수 있다. 이유: 요청 SHOP-42. 문서: [수량 상한](shopping/장바구니.md#수량-상한)"
+```
+
+`log add`는 제목이나 본문에 `<!--`가 있으면 거부해요.
+
+`[확인 필요]` 질문이 답을 얻으면 `decision` 항목을 남기고, 확정한 정책 본문 끝에 결정 링크 하나를 둬요. 문서 안에 변경 이력을 두지 않는 대신 결정은 로그에 쌓이고 문서는 링크로만 가리켜요. 슬러그는 대괄호·`|`·쉼표·콜론을 빼므로, `|`가 있던 자리는 `--`가 돼요.
+
+```markdown
+## [2026-11-02] decision | 최소 주문 금액: 10,000원은 배송비 정책에서 온 값이다
+결과: 합계 10,000원 미만이면 결제 버튼이 비활성이다. 이유: 2026-11-02 기획 확인. 문서: [최소 주문 금액](shopping/장바구니.md#최소-주문-금액)
+```
+
+```markdown
+### 최소 주문 금액
+합계가 10,000원 미만이면 결제 버튼을 비활성화한다. (결정: [2026-11-02](../log.md#2026-11-02-decision--최소-주문-금액-10000원은-배송비-정책에서-온-값이다))
+```
+
+kind는 `ingest`(원본 자료 반영), `query`(답을 찾아 환류), `lint`, `drift`, `change`(문서 변경), `decision`(질문 확정)이에요.
+
+## 스킬
+
+`init --skills`는 에이전트가 crumbs 문서를 다루는 절차를 `.claude/skills/<이름>/SKILL.md`(Claude Code)와 `.agents/skills/<이름>/SKILL.md`(Codex)에 설치해요. 기존 `SKILL.md`는 덮어쓰지 않으니 새 버전으로 바꾸려면 지우고 다시 설치해요. Claude Code는 `CLAUDE.md`에 `@AGENTS.md`가 있어야 crumbs 블록의 규칙을 읽어요.
+
+생성된 SKILL.md는 frontmatter 바로 뒤에 그것을 만든 crumbs-spec 버전을 적은 주석 한 줄을 둬요. 스킬과 템플릿은 패키지 버전을 따라요. 마이너 릴리스는 문구를 바꿀 수 있고 패치 릴리스는 바꾸지 않아요. 새 버전으로 올리려면 파일을 지우고 `init --skills`를 다시 실행해요.
+
+| 스킬 | 하는 일 |
+|---|---|
+| `crumbs-writer` | 문서를 쓰거나 갱신해요. "변경 반영"(바뀐 코드 → 소유 문서)과 "기존 코드 문서화"(코드·테스트만으로 처음 쓰기) 두 모드. 책임 단위, 문체, 질문 형식, 흐름 도식, 개념 페이지 기준을 담고 있어요 |
+| `crumbs-finder` | 인덱스 → 개요 → 상세 순으로 답을 찾아 출처와 함께 답하고, 좋은 답은 `query` 로그로 환류해요 |
+| `crumbs-interview` | 요청이 건드리는 정책 중 미확인인 것을 질문으로 만들고 멈춰요 |
+| `crumbs-ingest` | `docs/raw/`의 새 자료를 읽고 영향 문서를 찾아 확인받은 뒤 반영하고 `ingest` 로그를 남겨요 |
+
+## 사용 예시
+
+### 1. 기존 코드를 처음 문서화해요
+
+```
+src/cart/ 아래 코드를 crumbs-writer의 "기존 코드 문서화" 모드로 문서화해 줘.
+도메인 디렉터리는 docs/specs/shopping/이고, 확인하지 못한 정책은 질문으로 남기고 끝까지 해 줘.
+```
+
+에이전트는 인덱스와 템플릿을 읽고, 진입점부터 코드와 테스트를 따라가며 `shopping/overview.md`와 상세 문서를 만들어요. 테스트가 확정하는 규칙은 정책으로, 코드에만 있는 규칙은 "지금은 …" 서술과 `[확인 필요]` 질문으로 적어요. 끝에 `check`를 돌려 오류를 없애고 로그를 남겨요.
+
+```
+crumbs check: 문서 5개, 오류 0개, 경고 3개
+```
+
+경고 3개는 질문이 남은 문서 3개예요. 각 문서의 `확인 필요 사항` 절만 훑어도 무엇을 결정해야 하는지 알 수 있어요.
+
+### 2. 코드 변경을 문서에 반영해요
+
+```
+장바구니 수량 상한을 99에서 199로 올렸어. 문서도 맞춰 줘.
+```
+
+writer는 `grep -rl 'src/cart/cart.ts' docs/specs`로 근거에 그 경로를 적은 소유 문서를 찾고, "현재 동작"과 `### 수량 상한` 본문을 고치고, 흐름 도식의 값을 맞추고, 로그에 `change | 장바구니 수량 상한을 199로 올림`을 남겨요. 소유 문서가 둘로 보이면 멈추고 어느 쪽이 소유자인지 물어요.
+
+### 3. 모르는 정책은 묻고, 답은 결정으로 남겨요
+
+```
+쿠폰 중복 적용 규칙을 바꾸려고 해. 먼저 뭘 확인해야 하지?
+```
+
+interview가 요청이 건드리는 정책을 나열하고, 코드·테스트·원본으로 확인된 것과 미확인인 것을 가른 뒤 미확인 정책을 질문으로 내요. 답하시면 writer가 정책을 확정 서술로 바꾸고 `decision` 로그와 결정 링크를 남겨요.
+
+### 4. 원본 자료를 반영해요
+
+```
+docs/raw/coupon-policy-v3.pdf를 반영해 줘.
+```
+
+ingest가 자료를 읽고 영향을 받는 문서를 인덱스·역링크·근거로 찾아 "바꿀 내용 목록"을 먼저 보여 줘요. 확인을 받은 뒤에만 소유 문서를 고치고 `ingest` 로그를 남겨요. 자동 병합은 하지 않아요.
+
+### 5. 답을 찾아요
+
+```
+장바구니에 몇 개까지 담을 수 있어?
+```
+
+finder는 인덱스 → 쇼핑 개요 → 장바구니 문서 순으로 내려가 `### 수량 상한`을 출처로 답해요. 용어·개념 질문이면 `concepts/overview.md`의 용어 절을 먼저 봐요. 문서에 답이 없으면 "문서에 없음"과 가장 가까이 간 문서를 말해요.
+
+### 6. CI에서 검사해요
+
+오류가 있으면 실패하는 GitHub Actions 작업의 예시예요.
+
+```yaml
+jobs:
+  specs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npx crumbs-spec check --format json > crumbs-report.json
+```
+
+종료 코드 1이면 오류가 있어요. 경고(`open-question`, `missing-flow` 등)는 실패시키지 않아요.
+
+## 종료 코드
+
+| 코드 | 의미 |
+|---|---|
+| 0 | `check`: 오류가 없어요(경고는 허용). `init`·`log add`: 완료 |
+| 1 | `check`: 오류가 하나 이상 있어요 |
+| 2 | 사용법 오류, 설정 오류, 예기치 않은 I/O 오류 |
+
+## 설계에서 뺀 것
+
+- 요구사항 ID, front matter, EARS 같은 문법 강제. 탐색 정보는 링크와 제목에만 둬요.
+- 문서 안의 변경 이력 표와 결정마다 별도 파일. 결정은 로그 한 곳에 쌓고 문서는 링크로 가리켜요.
+- 정의만 있는 용어 페이지. 개요의 용어 절로 충분해요.
+- `check`의 문체·내용 판정. 문체는 스킬 지침과 [docs/lint/](docs/lint/README.md)의 markdownlint 설정 샘플이 맡아요.
+
+## 테스트와 호환성
+
+`npm test`는 CI에서 Linux와 macOS 위에서 node:test 케이스 80여 개를 돌려요(`.github/workflows/ci.yml` 참고). 변경 내역은 [CHANGELOG.md](CHANGELOG.md)에 있어요. 1.0 전에는 마이너 버전에서 검사 규칙, 템플릿, 스킬 문구가 바뀔 수 있고, 패치 버전은 버그만 고쳐요.
+
+## 로드맵
+
+| 단계 | 내용 | 상태 |
+|---|---|---|
+| 1 | `init`, `check`, 템플릿, AGENTS 블록 | 완료 |
+| 2 | 스킬 4종, `log add`, 흐름 절, 책임 단위 기준, 용어·개념 페이지, 결정 로그 | 완료 |
+| 3 | `crumbs reverse <path>` — 코드에서 초안 생성 명령(지금은 writer 스킬이 대신해요) | 예정 |
+| 4 | `crumbs drift --base <ref>` — diff로 근거가 바뀐 문서를 찾아요 | 예정 |
+| 5 | 예제 앱과 탐색 비용 벤치마크 러너 | 예정 |