crumbs-spec 0.1.0 → 0.2.0

package/README.ko.md

@@ -2,6 +2,8 @@
 
 **한국어** · [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)
+
 에이전트가 길을 잃지 않게 문서마다 빵부스러기(링크)를 남기고, 인덱스에서 상세 문서까지 한 길로 이어지는 **살아 있는 스펙**을 만들어요. 저장소가 *지금* 어떻게 동작하는지를 책임 단위 문서로 두고, 그 문서들이 잘 이어져 있는지 명령 하나로 검사하고, 에이전트가 문서를 쓰고·찾고·묻고·반영하는 절차를 스킬로 고정한 도구예요.
 
 ## 왜 만들었나요
@@ -22,40 +24,46 @@ Spec Kit은 구현 전 계획을, LLM Wiki는 자료를 쌓는 위키를 잘 다
 |---|---|---|---|---|
 | 문서 단위 | 변경(기능) 하나: `spec.md`·`plan.md`·`tasks.md` | 현재 상태 스펙 + 변경 델타 | 엔티티·개념·원본 요약 페이지 | **책임(사용자 흐름) 하나**. 정책은 문서 하나가 소유 |
 | 시점 | 구현 전 | 구현 전·후 | 자료 반영 시점 | **구현 뒤 현재 동작** |
-| 기존 코드 | "추론하지 않는다"고 스스로 밝힘 | 온보딩은 있으나 코드→스펙 초안은 없음 | 원본 자료가 대상, 코드 아님 | **코드·테스트에서 초안을 만들고 모르는 것은 `[확인 필요]` 질문으로** |
+| 기존 코드 | "추론하지 않는다"고 스스로 밝힘 | 온보딩은 있으나 코드→스펙 초안은 없음 | 원본 자료가 대상, 코드 아님 | **crumbs-writer 스킬이 코드·테스트에서 초안을 만들고, 모르는 것은 `[확인 필요]` 질문으로 남겨요** |
 | 탐색 | 폴더와 파일 이름 | 폴더와 파일 이름 | 인덱스 우선 | **인덱스 → 개요 → 상세 링크만**. ID·front matter 없음 |
-| 기계 검사 | spec·plan·tasks 일관성 | 델타 병합 | 고아 페이지·끊긴 링크 lint(LLM 판단 포함) | **결정론적 15개 규칙**: 링크·앵커·도달 가능·역링크·정책 중복·근거 경로 실존·절 순서·흐름 도식·로그 형식 |
-| 구현 후 동기화 | 팀이 유지 방식을 고름 | `archive`/`sync`로 변경분만 | 질의 결과를 위키에 환류 | **에이전트 규칙("요청 없어도 같은 변경에서 문서 갱신") + 결정 로그 + 예정된 `drift`** |
+| 기계 검사 | 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`가 세어 줘요.
+- **추측 금지.** 코드·테스트·승인된 자료로 확인되지 않은 규칙은 "지금은 이렇게 동작한다" 서술과 `[확인 필요]` 질문으로만 남겨요. `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분 |
+| 도메인 | 코드 범위 | 만든 문서 | 정책 (확정 / 미해결 질문) | 에이전트 토큰 | 작성 시간 |
+|---|---|---|---|---|---|
+| 결제 | 약 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분쯤에 모두 끝났어요. 지어낸 정책은 0개였고, 기존 스펙 문서와 코드가 달랐던 6곳을 모두 코드대로 적었어요. 그 뒤 사용자 흐름 단위로 다시 묶어 38개 문서가 됐어요.
+작성 시간은 에이전트 전사의 타임스탬프에서 10분 넘게 비어 있던 대기 시간을 뺀 실제 작업 시간이에요. 세 도메인을 병렬로 돌려 1시간 15분쯤에 모두 끝났어요. 작성자가 결과를 직접 검토했을 때 지어낸 정책은 없었고, 기존 스펙과 코드가 달랐던 6곳은 코드대로 적었어요. 이 검토는 작성자가 했고 독립적으로 하지 않았어요. 그 뒤 사용자 흐름 단위로 다시 묶어 38개 문서가 됐어요.
 
 **같은 질문 18개로 비교한 탐색 비용** (에이전트는 문서만 읽고 코드는 금지)
 
+정답 수는 crumbs가 적었지만(18개 중 15개 대 17개), 읽은 파일과 토큰은 더 적었어요.
+
 | | 기존 스펙 체계 | crumbs-spec |
 |---|---|---|
 | 정답 | 17 / 18 (부분 1) | 15 / 18 (부분 3) |
@@ -63,7 +71,7 @@ LLM Wiki에서는 원본/위키/스키마 분리, 인덱스 우선, 추가 전
 | 검색(grep)으로 떨어진 횟수 | 3 | 1 |
 | 토큰 합계 | 232만 | 189만 (−18%) |
 
-기존 체계의 부분 정답은 소유 문서를 못 찾은 경우였고, crumbs의 부분 정답 3개는 모두 문서엔 3~5파일로 도달했는데 writer가 화면 수치·채널 분기 같은 세부를 버린 경우였어요. 그 원인은 스킬 규칙("조건이 붙은 값은 버리지 않는다")으로 고쳤어요. 질문이 기존 스펙에서 나와 기존 체계에 유리한 편향이 있다는 점은 감안해 주세요.
+기존 체계의 부분 정답은 소유 문서를 못 찾은 경우였고, crumbs의 부분 정답 3개는 모두 문서엔 3~5파일로 도달했는데 writer가 화면 수치·채널 분기 같은 세부를 버린 경우였어요. 그 원인에 대해 스킬 규칙("조건이 붙은 값은 버리지 않는다")을 추가했어요. 벤치마크는 다시 돌리지 않았어요. 질문이 기존 스펙에서 나와 기존 체계에 유리한 편향이 있다는 점은 감안해 주세요.
 
 ## 설치와 빠른 시작
 
@@ -77,7 +85,7 @@ npx crumbs-spec check               # 링크 그래프와 구조 검사
 
 한국어 저장소는 `--lang ko`를 붙여요.
 
-`init`은 다음 일곱 파일을 만들고, 이미 있는 파일은 절대 덮어쓰지 않아요.
+`init`은 다음 파일을 만들고, 이미 있는 파일은 절대 덮어쓰지 않아요. `--skills all`이면 SKILL.md 여덟 개도 함께 써요. AGENTS.md에서는 `<!-- crumbs:start -->`와 `<!-- crumbs:end -->` 사이의 자기 블록만 바꿔요.
 
 ```
 crumbs.json                      설정
@@ -89,7 +97,9 @@ docs/raw/README.md               원본 자료 디렉터리(읽기 전용)
 AGENTS.md                        crumbs 블록(에이전트 규칙)
 ```
 
-npm에 공개하기 전에는 저장소에서 `npm run build` 뒤 `node dist/src/cli.js <명령>`으로 실행해요.
+`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 <명령>`으로 실행해요.
 
 ## 기존 프로젝트에 추가하기
 
@@ -112,11 +122,11 @@ npm에 공개하기 전에는 저장소에서 `npm run build` 뒤 `node dist/src
    도메인 디렉터리는 docs/crumbs/billing/이다. 확인하지 못한 정책은 질문으로 남기고 끝까지 해 줘.
    ```
 
-5. **`check`를 CI에 걸어요.** 오류(끊어진 링크·앵커, 도달 불가 문서, 빠진 역링크, 없는 코드 경로, 정책 이름 중복)만 실패시키고 경고는 둬요. 아직 crumbs로 다루지 않는 디렉터리가 스펙 루트 안에 있으면 `crumbs.json`의 `exclude`에 넣어요.
+5. **`check`를 CI에 걸어요.** 오류(끊어진 링크·앵커, 도달 불가 문서, 빠진 역링크, 없는 코드 경로, 정책 이름 중복)만 실패시키고 경고는 무시해요. 스펙 루트 안의 Markdown 가운데 아직 crumbs 문서가 아닌 것은 `crumbs.json`의 `exclude`에 넣어요. 항목은 스펙 루트 기준 상대 경로이고, `/`로 끝나면 그 디렉터리를 제외해요. 글롭 패턴은 없어요. 필수 절이 하나도 없는 문서는 `check`가 알려 줘요.
 
 6. **코드를 바꿀 때 문서를 같이 바꿔요.** AGENTS 블록이 "요청이 없어도 같은 변경에서 소유 문서를 갱신한다"를 에이전트에게 요구하니까, PR마다 `check`와 로그 항목이 함께 들어와요. 도메인이 하나씩 늘어나면서 인덱스가 채워져요.
 
-기존 스펙 체계가 있다면 두 체계에 같은 질문을 던져 비교해 보세요. 읽은 파일 수와 정답률로 어느 쪽이 더 잘 찾히는지 바로 보여요(5단계 벤치마크 러너가 이걸 자동화할 예정이에요).
+기존 스펙 체계가 있다면 두 체계에 같은 질문을 던져 비교해 보세요. 읽은 파일 수와 정답률로 어느 쪽이 더 잘 찾히는지 바로 보여요.
 
 ## 스펙이 만들어지는 순서
 
@@ -162,7 +172,7 @@ docs/raw/                        계약서·기획 메모 같은 불변 원본
 | 현재 동작 | 사용자가 겪는 대로, 현재형으로. 단계가 셋 이상이면 `###` 소제목 |
 | 흐름 | 두 단계 이상이면 Mermaid 도식, 비교 축이 둘 이상이면 표 |
 | 정책 | `### 정책 이름`(저장소 전체에서 유일)과 규칙. 미확정이면 지금 동작 서술 뒤에 `[확인 필요]` 질문 |
-| 근거 | 백틱 코드 경로와 설명. `check`가 경로의 존재를 확인해요 |
+| 근거 | `/`가 들어간 백틱 경로와 설명. `check`가 경로의 존재를 확인해요 |
 | 확인 필요 사항 | `- [확인 필요] [정책 이름](#앵커) — 질문` |
 | 관련 문서 | 개요로 가는 링크와 이웃 문서. 역링크는 상호여야 해요 |
 
@@ -225,25 +235,29 @@ npx crumbs-spec log add --kind <ingest|query|lint|drift|change|decision> "<제
 
 ```
 docs/specs/shopping/장바구니.md:34 error broken-anchor: 앵커가 없음: 쿠폰-할인.md#적용-순서
-docs/specs/shopping/장바구니.md:20 warning open-question: 미해결 질문 표시 2개
+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` | 오류 | 링크 대상 파일·제목이 없어요 |
+| `broken-link` | 오류 | 링크 대상 파일이 없거나, 철자(대소문자·유니코드 정규화)가 디스크의 파일과 달라요 |
+| `broken-anchor` | 오류 | 링크가 가리키는 제목(앵커)이 없어요 |
 | `unreachable` | 오류 | 인덱스에서 링크로 닿을 수 없는 문서예요 |
 | `missing-section` | 오류 | 역할별 필수 절이 없어요 |
 | `missing-backlink` | 오류 | 부모(개요·인덱스)로 돌아가는 링크가 없거나, 상세 A→B 링크에 B→A가 없어요 |
 | `missing-code-path` | 오류 | 근거의 코드 경로가 존재하지 않아요 |
-| `duplicate-policy` | 오류 | 같은 정책 이름이 두 문서에 있어요 |
-| `log-format` | 오류 | 로그 항목이 `## [YYYY-MM-DD] kind \| 제목` 형식이 아니에요 |
-| `open-question` | 경고 | 문서의 `[확인 필요]` 수예요 |
+| `duplicate-policy` | 오류 | 같은 정책 이름이 두 문서에 있거나 한 문서에 두 번 있어요 |
+| `log-format` | 오류 | 로그 항목이 `## [YYYY-MM-DD] kind \| 제목` 형식이 아니거나, 날짜가 하루를 넘어 미래예요 |
+| `unterminated-comment` | 오류 | HTML 주석이 열린 뒤 닫히지 않아, 그 뒤의 문서 전체가 가려져요 |
+| `open-question` | 경고 | 질문이 남은 문서마다 경고 하나예요. 개수는 미해결 질문 수예요 |
 | `log-order` | 경고 | 로그 날짜가 역순이에요 |
 | `missing-flow` | 경고 | 현재 동작이 6단계 이상인데 도식도 표도 없어요 |
 | `section-order` | 경고 | 절 순서가 템플릿과 달라요 |
@@ -258,7 +272,9 @@ npx crumbs-spec log add --kind change "장바구니 수량 상한을 99로 올
   --body "결과: 한 줄에 99개까지 담을 수 있다. 이유: 요청 SHOP-42. 문서: [수량 상한](shopping/장바구니.md#수량-상한)"
 ```
 
-`[확인 필요]` 질문이 답을 얻으면 `decision` 항목을 남기고, 확정한 정책 본문 끝에 결정 링크 하나를 둬요. 문서 안에 변경 이력을 두지 않는 대신 결정은 로그에 쌓이고 문서는 링크로만 가리켜요.
+`log add`는 제목이나 본문에 `<!--`가 있으면 거부해요.
+
+`[확인 필요]` 질문이 답을 얻으면 `decision` 항목을 남기고, 확정한 정책 본문 끝에 결정 링크 하나를 둬요. 문서 안에 변경 이력을 두지 않는 대신 결정은 로그에 쌓이고 문서는 링크로만 가리켜요. 슬러그는 대괄호·`|`·쉼표·콜론을 빼므로, `|`가 있던 자리는 `--`가 돼요.
 
 ```markdown
 ## [2026-11-02] decision | 최소 주문 금액: 10,000원은 배송비 정책에서 온 값이다
@@ -267,7 +283,7 @@ npx crumbs-spec log add --kind change "장바구니 수량 상한을 99로 올
 
 ```markdown
 ### 최소 주문 금액
-합계가 10,000원 미만이면 결제 버튼을 비활성화한다. (결정: [2026-11-02](../log.md#2026-11-02-decision-최소-주문-금액-10000원은-배송비-정책에서-온-값이다))
+합계가 10,000원 미만이면 결제 버튼을 비활성화한다. (결정: [2026-11-02](../log.md#2026-11-02-decision--최소-주문-금액-10000원은-배송비-정책에서-온-값이다))
 ```
 
 kind는 `ingest`(원본 자료 반영), `query`(답을 찾아 환류), `lint`, `drift`, `change`(문서 변경), `decision`(질문 확정)이에요.
@@ -276,6 +292,8 @@ kind는 `ingest`(원본 자료 반영), `query`(답을 찾아 환류), `lint`, `
 
 `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` | 문서를 쓰거나 갱신해요. "변경 반영"(바뀐 코드 → 소유 문서)과 "기존 코드 문서화"(코드·테스트만으로 처음 쓰기) 두 모드. 책임 단위, 문체, 질문 형식, 흐름 도식, 개념 페이지 기준을 담고 있어요 |
@@ -298,7 +316,7 @@ src/cart/ 아래 코드를 crumbs-writer의 "기존 코드 문서화" 모드로
 crumbs check: 문서 5개, 오류 0개, 경고 3개
 ```
 
-경고는 남긴 질문의 수예요. `확인 필요 사항` 절만 훑어도 무엇을 결정해야 하는지 알 수 있어요.
+경고 3개는 질문이 남은 문서 3개예요. 각 문서의 `확인 필요 사항` 절만 훑어도 무엇을 결정해야 하는지 알 수 있어요.
 
 ### 2. 코드 변경을 문서에 반영해요
 
@@ -334,8 +352,17 @@ finder는 인덱스 → 쇼핑 개요 → 장바구니 문서 순으로 내려
 
 ### 6. CI에서 검사해요
 
+오류가 있으면 실패하는 GitHub Actions 작업의 예시예요.
+
 ```yaml
-- run: npx crumbs-spec check --format json > crumbs-report.json
+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` 등)는 실패시키지 않아요.
@@ -355,6 +382,10 @@ finder는 인덱스 → 쇼핑 개요 → 장바구니 문서 순으로 내려
 - 정의만 있는 용어 페이지. 개요의 용어 절로 충분해요.
 - `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 전에는 마이너 버전에서 검사 규칙, 템플릿, 스킬 문구가 바뀔 수 있고, 패치 버전은 버그만 고쳐요.
+
 ## 로드맵
 
 | 단계 | 내용 | 상태 |