---
paths:
  - "docs/**/*.md"
  - "README.md"
  - "src/README.md"
  - "src/tests/*.json"
---

# 문서 · 기록 규칙

문서는 한국어, 선언형 종결("~한다", "~이다"). 날짜는 `2026-10-23` 형식. 영어 식별자·명령·파일명은 백틱으로 감싼다.

## 어떤 변경이 어떤 문서를 바꾸는가

| 변경 | 반드시 갱신 |
| --- | --- |
| 사용자 동작·CLI 옵션·종료 코드·오류 코드 | `src/README.md` 해당 절 |
| `.isproj`/local JSON 필드 | `docs/code-design/13-isproj-project-format.md`, `docs/code-design/examples/msix.isproj`, `src/fixtures/InstallerProject.isproj` |
| 기능 추가·정책 결정 | `docs/changes/YYYY-MM-DD-<slug>.md` 신규 작성, 루트 `README.md` 링크 |
| 실제 도구를 돌린 시험 | `src/tests/verification-YYYY-MM-DD-<slug>.json` |
| 백로그 항목 진척 | `docs/backlog/README.md` 상태 열 |
| 범위 변경(1차/후속 이동) | `docs/code-design/12-msix-first-builder.md`, 백로그, `docs/plan/10-development-schedule.md` |

## 변경 기록(`docs/changes`) 구성

1. 제목과 첫 단락: 날짜, 무엇을 왜 바꿨는지, 범위 밖임을 명시할 것.
2. `## 사용` 또는 `## 결정`: 사용자 절차 또는 결정 목록.
3. `## 모델과 실행`: 프로젝트/로컬/계획/결과 필드와 실행 순서.
4. `## 확인 결과`: 실행한 검사와 **실행하지 않은 검사**를 모두 나열. 테스트 개수, 해시, 상태 문자열을 적는다.
5. `## 근거`: Microsoft Learn 등 외부 문서 링크.

## 검증 JSON(`src/tests/verification-*.json`)

- `date`, `checks`(불리언 맵), 실제 결과 객체(`buildId`, `sha256`, `status`, `signingReport` 등), `installationTest`, `notRun` 목록을 포함한다.
- 실행하지 않은 항목은 생략하지 않고 `"notRun"`으로 적는다. GUI 클릭 시험을 하지 않았으면 `"guiClickTest": "notRun"`.
- 로컬 경로가 들어가므로 공유 전에 검토한다. 토큰·개인 키·PFX 비밀번호는 절대 넣지 않는다.

## 금지 표현

- 실행하지 않은 것을 "확인했다"로 쓰지 않는다. 시안·설계 작성은 구현 완료 증빙이 아니다.
- "배포 준비 완료", "설치 검증 완료", "지원 인증"은 Windows VM 설치·업데이트·제거 증빙이 있을 때만.
- 백로그 ID를 완료로 표시하려면 해당 행의 완료 기준 전체가 충족돼야 한다. 일부 구현은 README의 "일부 구현" 문장으로 남긴다.

## 링크

- 저장소 내부 링크는 상대 경로. 깨진 링크를 만들지 않도록 대상 파일 존재를 확인한다.
- 루트 `README.md`는 색인 역할이다. 새 설계·매뉴얼·변경 문서를 만들면 한 줄로 추가한다.