specthread 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +139 -0
  2. package/dist/bin/check.d.ts +1 -0
  3. package/dist/bin/check.js +67 -0
  4. package/dist/bin/cli.d.ts +2 -0
  5. package/dist/bin/cli.js +26 -0
  6. package/dist/bin/generate.d.ts +1 -0
  7. package/dist/bin/generate.js +55 -0
  8. package/dist/checks/changelog.d.ts +8 -0
  9. package/dist/checks/changelog.js +30 -0
  10. package/dist/checks/headings.d.ts +3 -0
  11. package/dist/checks/headings.js +54 -0
  12. package/dist/checks/links.d.ts +8 -0
  13. package/dist/checks/links.js +66 -0
  14. package/dist/checks/markers.d.ts +2 -0
  15. package/dist/checks/markers.js +60 -0
  16. package/dist/checks/pending.d.ts +2 -0
  17. package/dist/checks/pending.js +200 -0
  18. package/dist/checks/references.d.ts +2 -0
  19. package/dist/checks/references.js +41 -0
  20. package/dist/checks/sections.d.ts +3 -0
  21. package/dist/checks/sections.js +137 -0
  22. package/dist/checks/style.d.ts +10 -0
  23. package/dist/checks/style.js +61 -0
  24. package/dist/checks/timestamps.d.ts +2 -0
  25. package/dist/checks/timestamps.js +58 -0
  26. package/dist/checks/toc.d.ts +2 -0
  27. package/dist/checks/toc.js +41 -0
  28. package/dist/commands/init.d.ts +1 -0
  29. package/dist/commands/init.js +115 -0
  30. package/dist/config-loader.d.ts +2 -0
  31. package/dist/config-loader.js +106 -0
  32. package/dist/config.schema.d.ts +96 -0
  33. package/dist/config.schema.js +27 -0
  34. package/dist/constants/docs.d.ts +15 -0
  35. package/dist/constants/docs.js +16 -0
  36. package/dist/constants/patterns.d.ts +24 -0
  37. package/dist/constants/patterns.js +24 -0
  38. package/dist/constants/rules.d.ts +101 -0
  39. package/dist/constants/rules.js +97 -0
  40. package/dist/gen/pending-section.d.ts +19 -0
  41. package/dist/gen/pending-section.js +102 -0
  42. package/dist/gen/references.d.ts +13 -0
  43. package/dist/gen/references.js +144 -0
  44. package/dist/gen/summary.d.ts +27 -0
  45. package/dist/gen/summary.js +125 -0
  46. package/dist/gen/toc.d.ts +25 -0
  47. package/dist/gen/toc.js +66 -0
  48. package/dist/types.d.ts +125 -0
  49. package/dist/types.js +1 -0
  50. package/dist/utils/anchor.d.ts +20 -0
  51. package/dist/utils/anchor.js +24 -0
  52. package/dist/utils/ignore.d.ts +11 -0
  53. package/dist/utils/ignore.js +20 -0
  54. package/dist/utils/parse.d.ts +50 -0
  55. package/dist/utils/parse.js +272 -0
  56. package/dist/utils/report.d.ts +17 -0
  57. package/dist/utils/report.js +38 -0
  58. package/dist/utils/resolve.d.ts +21 -0
  59. package/dist/utils/resolve.js +157 -0
  60. package/dist/utils/scan.d.ts +11 -0
  61. package/dist/utils/scan.js +111 -0
  62. package/dist/utils/scope.d.ts +51 -0
  63. package/dist/utils/scope.js +55 -0
  64. package/package.json +29 -0
  65. package/scaffold/AGENTS.md +67 -0
  66. package/scaffold/CLAUDE.md +1 -0
  67. package/scaffold/claude/skills/check.md +43 -0
  68. package/scaffold/claude/skills/gen.md +41 -0
  69. package/scaffold/claude/skills/plan-close.md +57 -0
  70. package/scaffold/claude/skills/plan-open.md +50 -0
  71. package/scaffold/claude/skills/plan-run.md +51 -0
  72. package/scaffold/config.jsonc +71 -0
  73. package/scaffold/pending.md +34 -0
  74. package/scaffold/project.md +47 -0
  75. package/scaffold/rules.md +421 -0
  76. package/scaffold/templates/plan.md +159 -0
  77. package/scaffold/templates/spec.md +96 -0
@@ -0,0 +1,47 @@
1
+ # 프로젝트 고유 값
2
+
3
+ **목차**
4
+
5
+ - [1. 개요](#1-개요)
6
+ - [2. 마커와 미확정 사항](#2-마커와-미확정-사항)
7
+ - [참조](#참조)
8
+ - [미확정 사항](#미확정-사항)
9
+ - [변경 이력](#변경-이력)
10
+
11
+ ## 1. 개요
12
+
13
+ `config.jsonc` 가 정의하는 설정값의 **맥락과 근거**를 담는 문서. 값 자체는 config 가 정본이고, 이 문서는 "왜 이 값인가"를 설명한다.
14
+
15
+ ## 2. 마커와 미확정 사항
16
+
17
+ 형식과 체계는 [`rules.md` §4](./rules.md#4-미확정-관리) 가 갖는다. 종류 값과 시점 라벨은 `config.markers` 가 정본이다.
18
+
19
+ ### 2-1. 종류별 맥락
20
+
21
+ `config.markers.types` 에 정의된 종류의 의미와 처리자를 설명한다.
22
+
23
+ | 종류 | 의미 | 처리자 |
24
+ |-----|-----|-------|
25
+ | `system` | 코어 예약 - 문서·협업 체계 | |
26
+
27
+ `system` 은 코어가 이름과 의미를 정의한다. 프로젝트는 처리자만 채운다.
28
+
29
+ ### 2-2. 미확정 사항 파일
30
+
31
+ 이름은 [`pending.md`](./pending.md) 다. `config.jsonc` 에서 경로를 override 할 수 있다.
32
+
33
+ ## 참조
34
+
35
+ ### 문서
36
+
37
+ - [`rules.md`](./rules.md) - §2
38
+ - [`pending.md`](./pending.md) - §2-2
39
+
40
+ ## 미확정 사항
41
+
42
+ 해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([`pending.md`](./pending.md)).
43
+
44
+ ## 변경 이력
45
+
46
+ | 날짜 | 내용 |
47
+ |-----|-----|
@@ -0,0 +1,421 @@
1
+ # 문서 규칙
2
+
3
+ **목차**
4
+
5
+ - [1. 개요](#1-개요)
6
+ - [2. 수평 규칙](#2-수평-규칙)
7
+ - [3. 참조 방식](#3-참조-방식)
8
+ - [4. 미확정 관리](#4-미확정-관리)
9
+ - [5. 규칙 변경 절차](#5-규칙-변경-절차)
10
+ - [참조](#참조)
11
+ - [미확정 사항](#미확정-사항)
12
+ - [변경 이력](#변경-이력)
13
+
14
+ ## 1. 개요
15
+
16
+ 이 프로젝트의 모든 문서가 따르는 형식 규칙. **도메인과 무관한 부분만** 담는다. 경로·마커 종류·상용구처럼 이 프로젝트에서만 성립하는 값은 [`project.md`](./project.md) 가 갖는다.
17
+
18
+ | 파일 | 담는 것 | 층 |
19
+ |-----|-------|---|
20
+ | `rules.md` | 형식 규칙, 참조 방식, 미확정 관리 | 코어 |
21
+ | [`project.md`](./project.md) | 이 프로젝트 고유 값 | 커스텀 |
22
+ | `spec.md` 템플릿 | 시스템 명세 템플릿 | 코어 |
23
+ | `plan.md` 템플릿 | 작업 계획 템플릿 | 코어 |
24
+
25
+ **어느 유형이 어느 템플릿을 쓰는지는 `config.docTypes` 가 정의한다.** 위 표는 파일 목록과 층 표시만 담는다.
26
+
27
+ ## 2. 수평 규칙
28
+
29
+ | # | 규칙 | 상세 |
30
+ |---|-----|-----|
31
+ | 1 | 본문에 시점·버전을 남기지 않는다 | §2-1 |
32
+ | 2 | 참조는 링크로 건다 | §3-5. 이름만 적지 않는다. **코드 경로도 링크로** (§3-3 자동 수집 전제) |
33
+ | 3 | 변경 이력은 하단에 커밋 단위로 | §2-4 |
34
+ | 4 | 마커는 `PENDING::<종류>::<slug>` | §4-1 |
35
+ | 5 | 추적 없는 미확정을 두지 않는다 | §4-2 |
36
+ | 6 | 빈 섹션에는 사유를 적는다 | `해당 없음 - <이유>` 또는 마커. 제목만 두지 않는다 |
37
+ | 7 | 상단 메타를 두지 않는다 | 상태 값 / `최종 수정:` / 상단 의존 표기 모두 없음 |
38
+ | 8 | 꼬리 절은 무번호 | 참조 / 미확정 사항 / 변경 이력. 이름으로 참조한다 |
39
+ | 9 | 본문 절은 `§N-M` 완전 숫자 체계 | 그리스 문자·단독 알파벳 회피 |
40
+ | 10 | 도식은 mermaid 로 그린다 | §2-3 |
41
+ | 11 | 제목 바로 아래에 목차를 둔다 | §2-2 |
42
+ | 12 | 목록은 마크다운 목록으로 쓴다 | 인라인 나열 (`A · B · C`) 대신 `-` 항목으로 |
43
+ | 13 | 마커는 백틱으로 감싼다 | §4-1 |
44
+ | 14 | 꼬리 절 이름을 본문 절에 쓰지 않는다 | §2-5 |
45
+
46
+ ### 2-1. 본문에 남기지 않는 시점·버전 정보
47
+
48
+ 검사: `timestamp/body-date`
49
+
50
+ 문서 본문은 **현재 상태와 그 근거만** 서술한다. 아래는 전부 하단 변경 이력으로 보낸다.
51
+
52
+ | 유형 | 예 |
53
+ |-----|---|
54
+ | 날짜 | `(2026-08-09 결정)` |
55
+ | 마일스톤·주차 라벨 | `(M1 신규)` / `(W6 추가)` |
56
+ | 시점을 함의하는 단어 | _신규_ / _도입_ / _추가_ / _신설_ |
57
+ | 구버전 대비 서술 | _"구 X 폐기"_ / _"기존 Y 흡수 후 삭제"_ / _"이전 안은 Z"_ |
58
+ | 결정 사건 라벨 | _"사용자 결정 (날짜)"_ / _"결정 #5"_ / _"N 차 라운드에서 확정"_ |
59
+
60
+ **미래 시점도 같다.** `계획 (M2-B)` 처럼 _언제 할 것인가_ 를 spec 본문에 적지 않는다. 해결 예정은 관리 문서의 항목이 소유하므로 (§4-2) 본문에도 적으면 두 곳을 고쳐야 하고 한쪽이 낡는다.
61
+
62
+ 결정의 **내용** 과 **근거** 는 현재 상태이므로 본문에 남는다. 빼는 것은 _누가 언제 무엇을 뒤집었는가_ 라는 사건 기록이다. 코드 주석에도 같은 원칙이 걸린다.
63
+
64
+ ### 2-2. 목차
65
+
66
+ 검사:
67
+ - `toc/missing`
68
+ - `toc/stale`
69
+ - `heading/multiple-title`
70
+
71
+ 제목 다음에 목록으로 둔다.
72
+
73
+ ```markdown
74
+ **목차**
75
+
76
+ - [1. 개요](#1-개요)
77
+ - [2. 데이터 모델](#2-데이터-모델)
78
+ - [참조](#참조)
79
+ - [미확정 사항](#미확정-사항)
80
+ - [변경 이력](#변경-이력)
81
+ ```
82
+
83
+ - 표시 문자열은 제목 원문 그대로. 앵커는 마침표를 지우지만 (`1. 개요` → `#1-개요`) 목차 이름은 손대지 않는다
84
+ - `##` 레벨만 넣는다. `###` 까지 넣으면 목차가 본문보다 길어진다
85
+ - 꼬리 절도 넣는다
86
+ - 기계가 채운다. 생성기가 `##` 목록에서 만들고 검사기가 일치를 확인한다
87
+ - `#` 제목이 둘 이상이면 생성기가 그 문서를 건너뛴다
88
+
89
+ ### 2-3. 도식
90
+
91
+ **흐름·순서·상태 전이·의존 관계일 때만 mermaid 로 그린다.** 그 밖의 나열은 표나 목록으로 쓴다.
92
+
93
+ ASCII 박스 드로잉은 쓰지 않는다. 폭을 손으로 맞춰야 하고, 항목을 하나 추가하면 다시 그려야 하고, diff 가 읽히지 않는다.
94
+
95
+ ### 2-4. 변경 이력 형식
96
+
97
+ 검사: `changelog/order`
98
+
99
+ 문서 맨 아래에 `| 날짜 | 내용 |` 표로 둔다.
100
+
101
+ | 규칙 | 내용 |
102
+ |-----|-----|
103
+ | 단위 | 한 커밋 = 한 줄. 같은 커밋 안에서 변경이 더 생기면 그 줄을 고쳐 쓴다 |
104
+ | 순서 | 오래된 순. 새 줄은 표 맨 아래에 붙인다 |
105
+ | 다시 쓰기 | 줄은 유지하고 내용은 다시 쓸 수 있다. 줄을 합치거나 지우지 않는다 |
106
+
107
+ 정본은 git 이고 이 표는 요약본이다. 오래된 순인 이유는 최신 줄이 파일의 맨 끝에 놓여 가장 찾기 쉽고, diff 충돌 지점이 한 곳으로 고정되기 때문이다.
108
+
109
+ ### 2-5. 꼬리 절 이름은 예약어다
110
+
111
+ 검사:
112
+ - `heading/tail-name-reused`
113
+ - `heading/numbered-tail`
114
+
115
+ `참조` · `미확정 사항` · `변경 이력` 세 이름을 본문 절 제목으로 쓰지 않는다. 기계가 이름으로 꼬리 절 위치를 찾아 채우므로 (§3-3), 같은 이름의 본문 절이 있으면 엉뚱한 자리를 덮어쓸 수 있다.
116
+
117
+ 같은 주제를 다루는 본문 절에는 한정어를 붙인다 - `참조 방식` / `참조 규칙` 처럼.
118
+
119
+ ### 2-6. 문장 부호
120
+
121
+ 검사:
122
+ - `style/em-dash`
123
+ - `style/rule-undeclared`
124
+
125
+ **em dash 를 쓰지 않는다.** 하이픈 `-` 으로 적는다.
126
+
127
+ 강제: `no-em-dash` 훅 (프로젝트에서 설정). `config.features.emDash` 가 `false` 면 비활성화.
128
+
129
+ ## 3. 참조 방식
130
+
131
+ 참조는 관계의 성격에 따라 둘로 갈린다.
132
+
133
+ | | 대상 | 관계 | SSoT |
134
+ |---|-----|-----|------|
135
+ | **단순 참조** | 문서 → 문서 | 가리키기만 한다 | 다른 문서 |
136
+ | **보완 참조** | 문서 ↔ 코드·데이터 | 서로 채워준다 | 문서가 의미를, 코드가 값을 |
137
+
138
+ 지금은 대상 종류가 곧 판정 기준이 된다 (`.md` 냐 `.ts` / `.json` 이냐). 문서 ↔ 문서 보완 관계가 나오면 보완 참조 쪽을 넓힌다.
139
+
140
+ ### 3-1. 단순 참조
141
+
142
+ 검사:
143
+ - `link/target`
144
+ - `link/anchor`
145
+
146
+ 내용을 가리키기만 하는 것. 본문 안 그 자리에 인라인 링크로 건다. 본문에 건 링크는 하단 참조 절에 기계적으로 모인다 (§3-3).
147
+
148
+ **내용을 옮겨 적을 때는 반드시 정본 링크와 범위 한정을 붙인다.**
149
+
150
+ ```markdown
151
+ > **정본 2건**: auth.md / session.md
152
+ > 본 § 은 요약 + 인증 흐름 관련 부분만.
153
+ ```
154
+
155
+ 두 표기가 없으면 읽는 쪽이 이걸 정본으로 알고, 쓰는 쪽이 범위를 계속 넓힌다. 한 대상에 SSoT 는 하나다.
156
+
157
+ ### 3-2. 보완 참조
158
+
159
+ **코드·데이터가 값을 갖고, 문서가 의미를 갖는 것.** 서로가 서로를 필요로 한다.
160
+
161
+ | 종류 | 값의 정본 | 문서가 갖는 것 |
162
+ |-----|---------|------------|
163
+ | enum / 상수 | 코드 | 각 값의 의미 |
164
+ | 설정 / 데이터 | 데이터 파일 | 왜 이 구성인가, 역할 분담 |
165
+ | 조감 | 코드 (여러 파일에 흩어짐) | 한 장으로 모은 흐름 |
166
+ | 수치 / 제약 | **문서** | 검증 대상 값 자체 |
167
+
168
+ - 설정/데이터 종류는 항목의 내용을 전재하지 않는다. 이름·타입·역할 한 줄까지. 그 이상은 링크로
169
+ - 아직 데이터가 없는 항목도 본문에 둔다. 구현 여부는 링크 유무로 드러낸다
170
+ - 아직 정하지 않은 것은 미확정 사항 절로 간다
171
+ - 수치/제약은 문서가 정본이다. 판정 기준: _이 문서대로 코드가 짜였는지 검증할 수 있는가_
172
+ - 역방향 링크가 건강 지표다. 코드가 해당 절을 가리키지 않으면 검사기가 경고한다
173
+ - 한 대상에 소유 절은 하나다. 겹치는 쪽에 소유처를 한 줄 적는다
174
+
175
+ ### 3-3. 참조 절 - 기계 생성
176
+
177
+ 검사:
178
+ - `reference/missing`
179
+ - `reference/stale`
180
+
181
+ 문서 하단에 두고 본문 링크를 모아 자동으로 채운다. 사람이 쓰지 않는다.
182
+
183
+ ```markdown
184
+ ## 참조
185
+
186
+ ### 문서
187
+ - [`auth.md`](./auth.md) - §1, §4
188
+
189
+ ### 코드·데이터
190
+ - [`auth.config.ts`](../../src/config/auth.config.ts) - §3-1
191
+ ```
192
+
193
+ 같은 대상을 여러 번 가리키면 한 줄로 합치고 어느 절에서 참조됐는지를 붙인다.
194
+
195
+ **자동 로드되는 룰 문서는 참조 절을 두지 않는다.** 매 세션 통째로 읽히는 문서는 모든 줄의 비용을 반복해서 내고, 이미 사람이 큐레이션한 라우팅 표를 갖고 있다. 대상은 [`project.md`](./project.md) 가 지정한다.
196
+
197
+ ### 3-4. 참조와 절 폐기
198
+
199
+ 본문 절이 **링크만 담고 자체 설명이 없으면** 그 절은 존재 가치가 없다. 해당 내용을 인라인 참조로 대체하고 절을 지운다. 이것이 _절 폐기 판정_ 이다.
200
+
201
+ | 위치 | 규칙 |
202
+ |-----|-----|
203
+ | 인라인 링크 | 자유. 개수·위치·반복 제한 없음 |
204
+ | 본문 절 | 링크만 담은 절은 두지 않는다 (폐기 대상) |
205
+ | 하단 참조 절 | 유일한 예외. 링크만 담고 기계가 채운다 |
206
+
207
+ 인라인이든 절이든 내용을 옮겨 적었으면 정본 링크와 범위 한정을 붙인다 (§3-1). 판정 기준: **여기서 그 개념을 직접 설명했는가.**
208
+
209
+ ```markdown
210
+ 설명 안 함 (자유)
211
+ 인증 흐름은 [`auth.md`](./auth.md) 참조
212
+
213
+ 설명함 (정본 링크 필수)
214
+ 결제 취소는 상태 머신 전이로 처리된다.
215
+ (정본 [`payment.md`](./payment.md) §3 - 본 절은 취소 흐름만)
216
+ ```
217
+
218
+ 검사기가 참조를 수집할 때 이 판정이 부산물로 나온다.
219
+
220
+ | 검사기가 보는 것 | 판정 |
221
+ |--------------|-----|
222
+ | 코드를 가리키고 코드도 이 절을 가리킴 | 보완 참조. 정상 |
223
+ | 코드를 가리키는데 코드는 안 가리킴 | 보완 참조. 역방향 링크 누락 |
224
+ | 문서만 가리킴 + 자체 설명 있음 | 단순 참조. 정본 링크 표기 검사 |
225
+ | 문서만 가리킴 + 자체 설명 없음 | 절 폐기 대상 |
226
+
227
+ 판정은 절 단위다. 한 문서 안에 두 종류가 섞일 수 있다.
228
+
229
+ ### 3-5. 절을 가리키는 표기
230
+
231
+ 검사:
232
+ - `section-ref/missing`
233
+ - `section-ref/not-linked`
234
+ - `section-ref/unknown-doc`
235
+ - `section-ref/ambiguous-doc`
236
+ - `section-ref/no-doc-name`
237
+
238
+ 다른 문서의 절을 가리킬 때는 앵커 링크를 쓴다.
239
+
240
+ ```markdown
241
+ [`auth.md` §3](./auth.md#3-인증-흐름)
242
+ ```
243
+
244
+ | 자리 | 표기 | 이유 |
245
+ |-----|-----|-----|
246
+ | 문서 → 다른 문서 | 앵커 링크 | 링크를 걸 수 있다 |
247
+ | 문서 → 자기 절 | `§N` | 가릴 문서명이 없다 |
248
+ | 코드 주석 | `파일명 §N` | 주석에는 마크다운 링크가 없다 |
249
+
250
+ `§` 는 링크를 걸 수 없는 곳에서만 쓴다. 링크로 대체할 수 있는 자리에서는 앵커 링크를 우선한다. 어느 쪽이든 번호가 밀리면 깨지지만, 검사기가 잡으므로 조용히 어긋나지 않는다.
251
+
252
+ ## 4. 미확정 관리
253
+
254
+ 미확정은 세 곳에서 같은 slug ID 로 관리된다. 정본은 관리 문서 하나이고 나머지 둘은 생성된 뷰다.
255
+
256
+ 용어를 셋으로 고정한다.
257
+
258
+ - **미확정**: 아직 결정되지 않은 것 (개념어)
259
+ - **관리 문서**: 미확정 항목을 모아 두는 파일 (`pending.md`)
260
+ - **미확정 사항**: 각 문서 하단에 생성되는 `## 미확정 사항` 섹션
261
+
262
+ | 위치 | 역할 | 담는 것 |
263
+ |-----|-----|-------|
264
+ | 본문·코드 마커 | 발생 지점 표시 | slug + 힌트 한 줄까지 |
265
+ | 문서 미확정 사항 절 | 생성 뷰 | 관리 문서에서 가져옴 |
266
+ | 관리 문서 | **정본** | 상세 설명 + 백링크 |
267
+
268
+ 설명은 관리 문서에만 상세히 쓴다. 마커 옆에 긴 설명을 두면 관리 문서와 어긋난다.
269
+
270
+ `PENDING` 접두는 마커에만 붙는다. ID 자체는 세 위치가 같다.
271
+
272
+ | 위치 | 표기 | 모양 |
273
+ |-----|-----|-----|
274
+ <!-- @specthread-ignore -->
275
+ | 마커 | `PENDING::deps::auth-flow` | 산문·주석 안 |
276
+ | 관리 문서 항목 | `` `[deps::auth-flow]` `` | `###` 헤딩 |
277
+ | 문서 미확정 사항 절 | `` `[deps::auth-flow]` `` | `li` |
278
+
279
+ 마커는 산문 안에 박히므로 자기를 식별할 `PENDING` 접두가 필요하다. 관리 문서와 미확정 사항 절은 위치 자체가 맥락이므로 접두 없이 id 만 쓴다. `grep -c "PENDING::design"` 이 실제 발생 지점만 세는 것도 이 구분 덕분이다.
280
+
281
+ 미확정 사항 절은 관리 문서의 백링크를 뒤집어 자동 생성한다 (검사: `pending/section-stale`). 절이 이미 있는 문서만 채운다.
282
+
283
+ ### 4-1. 마커
284
+
285
+ 형식은 세 조각 고정이다.
286
+
287
+ ```
288
+ PENDING::<종류>::<slug>
289
+ ```
290
+
291
+ | 요소 | 규칙 |
292
+ |-----|-----|
293
+ | `PENDING` | 고정 접두 |
294
+ | 종류 | 소문자. `system` 은 코어 예약, 프로젝트 종류는 `config.markers.types` 에서 정의 |
295
+ | slug | 전역 유일, kebab-case |
296
+ | 구분자 | `::` 통일 |
297
+ | 표기 | 문서에서는 백틱으로 감싼다 |
298
+
299
+ **종류**는 미확정의 성격을 나타내며, 사실상 _누가 처리하는가_ 를 가른다. `system` 은 코어가 소유하는 예약 종류로, 문서 체계 자체에 대한 미확정에 붙인다. 코어 문서가 커스텀층 종류에 의존하면 다른 프로젝트에서 깨지므로 이 분리가 필요하다. 종류가 여러 성격에 걸칠 때는 **대상 도메인이 우선**한다. 차단 원인("다른 작업이 끝나야 한다" 등)은 종류가 아니라 관리 문서 항목 본문에 적는다.
300
+
301
+ **slug**는 관리 문서 항목과 1:1 또는 N:1 로 대응한다. 여러 곳에 흩어진 잠정 값에 같은 slug 를 붙이면 관리 문서 항목 하나에 백링크 여러 개로 잡힌다. 필요한 만큼 세분하거나 넓게 묶는다.
302
+
303
+ 마커에 넣지 않는 것:
304
+
305
+ - **해결 예정**: 마일스톤은 자주 밀린다. 관리 문서 항목이 소유한다
306
+ - **시점**: slug 에 `api-version-M2` 처럼 넣으면 시점이 바뀔 때 ID 가 바뀌고 모든 참조가 깨진다
307
+
308
+ ```
309
+ 코드 // PENDING::deps::auth-flow
310
+ 문서 `PENDING::design::cache-strategy`
311
+ JSON "_pending": "style::api-version"
312
+ ```
313
+
314
+ 힌트가 필요하면 마커 뒤에 ` - ` 로 한 줄까지 이어 붙인다.
315
+
316
+ 검사기가 양방향으로 확인한다.
317
+
318
+ - `marker/orphan`: 코드 마커 ID 가 관리 문서에 없음 (추적되지 않는 미확정)
319
+ - `marker/unmarked`: 관리 문서 항목 ID 가 코드나 문서에 없음 (이미 해결된 것)
320
+
321
+ ### 4-2. 관리 문서
322
+
323
+ 검사:
324
+ - `pending/item-shape`
325
+ - `pending/inline-body`
326
+ - `pending/inline-options`
327
+ - `pending/work-link`
328
+ - `pending/timepoint`
329
+ - `pending/summary-missing`
330
+ - `pending/summary-stale`
331
+
332
+ 미확정 항목을 `pending.md` 한 파일에 모으고 id 순으로 정렬한다.
333
+
334
+ 관리 문서 안에서 종류마다 `##` 섹션을 하나씩 둔다. 종류 값은 `config.markers.types` 가 정의한다.
335
+
336
+ ```markdown
337
+ ## 2. design
338
+ ## 3. system
339
+ ```
340
+
341
+ **항목 형식**
342
+
343
+ ```markdown
344
+ ### `[deps::auth-flow]` 인증 흐름 결정
345
+
346
+ 작성일 2026-05-02 / 해결 예정 M2
347
+
348
+ 현재 세션 기반이나 토큰 기반으로 전환이 논의 중이다.
349
+
350
+ - (a) JWT 기반 토큰으로 전환한다
351
+ - (b) 현행 세션 유지
352
+
353
+ 참조: [`auth.md` §2](../spec/auth.md), [`api.md` §4](../spec/api.md)
354
+ ```
355
+
356
+ | 조각 | 규칙 |
357
+ |-----|-----|
358
+ | 헤딩 | `###` + id + 제목. 본문을 이어 붙이지 않는다 |
359
+ | 시점 | 헤딩 다음 줄. `작성일 <날짜> / 해결 예정 <라벨>` |
360
+ | 본문 | 문단 단위 |
361
+ | 선택지 | `li` 로 낸다 |
362
+ | 참조 | 마지막 줄 |
363
+
364
+ - 항목이 `###` 헤딩인 이유: `li` 는 앵커가 없어서 다른 문서가 개별 항목을 가리킬 수 없다
365
+ - 시점을 헤딩에 넣지 않는 이유: 마일스톤이 밀리면 앵커가 바뀌고 링크가 깨진다
366
+ - 번호를 붙이지 않는 이유: 항목을 끼우면 뒤가 전부 밀린다. 항목은 id 로 가리킨다
367
+ - 본문에 굵기(`**`)를 쓰지 않는다. 정보를 굵기로 나르면 무엇이 중요한지 흐려진다
368
+ - 체크박스를 두지 않는다. 해결되면 항목을 지우므로 `[x]` 상태가 존재하지 않는다
369
+
370
+ **시점 표기**
371
+
372
+ `작성일`(항상 과거)과 `해결 예정`(항상 미래) 두 라벨로 구분한다. 해결 예정이 없으면 생략한다.
373
+
374
+ - 해결 예정에 달력 날짜를 쓰지 않는다. 작성일과 같은 모양이 되면 구분이 안 된다
375
+ - 라벨 값은 검사하지 않는다. 새 프로젝트는 마일스톤 목록이 비어 있으므로, 집합 검사를 걸면 첫 항목부터 위반이 된다. `config.markers.timepoints` 는 참고 목록이지 검사 관문이 아니다
376
+
377
+ **등록 기준**
378
+
379
+ _정하지 않으면 무엇이 막히는지_ 말할 수 있어야 한다. 이것이 미확정과 할 일을 가르는 기준이다. 아무것도 막지 않으면 담지 않는다. 이미 결정된 것은 해당 도메인 spec 이 갖는다.
380
+
381
+ - 슬러그만 두지 않는다. 무엇을 정해야 하는지 알 수 있어야 한다
382
+ - `docs/work/` 문서를 가리키지 않는다. 작업 문서는 흡수 후 사라지므로 근거를 항목 안으로 옮긴다
383
+ - 해결되면 항목을 지운다. 단순 해소는 변경 이력에도 적지 않는다 (`git log -p` 가 기록을 갖는다). slug 가 다른 항목으로 흡수된 경우만 이력에 메모한다
384
+
385
+ **자동 생성**
386
+
387
+ - 백링크: slug 로 `grep` 해서 코드·문서 위치를 자동 수집한다
388
+ - 요약 표: 각 절 머리에 `| id | 항목 | 해결 예정 | 걸린 곳 |` 표를 자동 생성한다. 세 열 모두 손으로 셀 수 없는 값이라 `stale` 검사로 어긋남을 잡는다
389
+ - 마커가 없는 미확정(문서 전체에 걸리는 것)도 담는다. 백링크에 해당 문서만 적는다
390
+
391
+ ## 5. 규칙 변경 절차
392
+
393
+ 문서를 고치다 보면 규칙이 안 맞는 곳이 나온다. 그때 바로 규칙을 바꾸지 않는다.
394
+
395
+ | 단계 | 처리 |
396
+ |-----|-----|
397
+ | 1 회차 발견 | 그 문서에서만 예외로 처리하고, 이 파일 미확정 사항에 ID 를 붙여 기록한다 |
398
+ | **2 회차 발견** | 규칙을 고친다. 한 번은 우연, 두 번은 패턴 |
399
+ | 규칙 변경 시 | 기록해둔 항목을 지우고 변경 이력에 한 줄 |
400
+
401
+ 기존 문서의 소급 적용:
402
+
403
+ | 변경 종류 | 소급 | 이유 |
404
+ |---------|-----|-----|
405
+ | **형식** (표기·순서·이름) | 한다 | 기계 치환이 되는 것만 |
406
+ | **구조** (절 추가·삭제·분할) | 안 한다 | 다음에 그 문서를 손댈 때 함께 |
407
+
408
+ ## 참조
409
+
410
+ ### 문서
411
+
412
+ - [`project.md`](./project.md) - §1, §3-3
413
+
414
+ ## 미확정 사항
415
+
416
+ 해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([`pending.md`](./pending.md)).
417
+
418
+ ## 변경 이력
419
+
420
+ | 날짜 | 내용 |
421
+ |-----|-----|
@@ -0,0 +1,159 @@
1
+ # Plan 템플릿
2
+
3
+ **목차**
4
+
5
+ - [1. 골격](#1-골격)
6
+ - [2. 채우는 법](#2-채우는-법)
7
+ - [참조](#참조)
8
+ - [미확정 사항](#미확정-사항)
9
+ - [변경 이력](#변경-이력)
10
+
11
+ 작업 계획 문서의 틀. 소규모 단일 작업부터 여러 단계로 나뉘는 큰 작업까지 하나의 구조로 다룬다.
12
+
13
+ ## 1. 골격
14
+
15
+ ```markdown
16
+ # <작업 이름>
17
+
18
+ **목차**
19
+
20
+ - [1. 목표](#1-목표)
21
+ - [2. 작업 단계](#2-작업-단계)
22
+ - [3. 작업 범위 상세](#3-작업-범위-상세)
23
+ - [4. 영향 파일](#4-영향-파일)
24
+ - [5. 다루지 않는 항목](#5-다루지-않는-항목)
25
+ - [6. 검증 기준](#6-검증-기준)
26
+ - [7. 예상 산출물](#7-예상-산출물)
27
+ - [참조](#참조)
28
+ - [미확정 사항](#미확정-사항)
29
+ - [변경 이력](#변경-이력)
30
+
31
+ ## 1. 목표
32
+
33
+ <무엇을 끝낸 상태인지 한 문단>
34
+
35
+ **종료 게이트**
36
+
37
+ - <검증 가능한 조건>
38
+
39
+ ## 2. 작업 단계
40
+
41
+ | # | 작업 | 상태 |
42
+ |---|-----|-----|
43
+ | 1 | <작업> | 대기 |
44
+
45
+ ## 3. 작업 범위 상세
46
+
47
+ ### 3-1. <sub-section>
48
+
49
+ <코드 시그니처 / 데이터 모양 / 예시>
50
+
51
+ ## 4. 영향 파일
52
+
53
+ ### 4-1. 신규
54
+
55
+ | 경로 | 역할 |
56
+ |-----|-----|
57
+
58
+ ### 4-2. 변경
59
+
60
+ | 경로 | 변경 |
61
+ |-----|-----|
62
+
63
+ ## 5. 다루지 않는 항목
64
+
65
+ | 항목 | 처리 | 이유 |
66
+ |-----|-----|-----|
67
+ | <항목> | <하지 않음 / 이관 / 다른 단계에 포함> | <근거> |
68
+
69
+ ## 6. 검증 기준
70
+
71
+ ### 6-1. 자동 검증
72
+
73
+ ### 6-2. 사용자 검증
74
+
75
+ ## 7. 예상 산출물
76
+
77
+ <이 작업이 끝나면 생기는 것. 코드 외에 갱신해야 할 문서가 있으면 함께 적는다.>
78
+
79
+ ## 참조
80
+
81
+ ### 문서
82
+ ### 코드·데이터
83
+
84
+ ## 미확정 사항
85
+
86
+ - `[<종류>::<slug>]` <한 줄 설명>
87
+
88
+ ## 변경 이력
89
+
90
+ | 날짜 | 내용 |
91
+ |-----|-----|
92
+ | YYYY-MM-DD | <한 커밋에 담긴 변경을 한 줄로> |
93
+ ```
94
+
95
+ ## 2. 채우는 법
96
+
97
+ ### 2-1. 목표
98
+
99
+ 종료 게이트는 **검증 가능한 조건만** 쓴다. "잘 정리됐다"는 게이트가 아니다.
100
+
101
+ ### 2-2. 작업 단계
102
+
103
+ **문서 전체의 진행 상태를 이 표 하나로 표현한다.** 상단에 별도 상태 표기를 두지 않는다.
104
+
105
+ 소규모 작업이면 단계가 1~2개일 수 있다. 그래도 표는 남겨둔다 - 완료 추적용.
106
+
107
+ ### 2-3. 작업 범위 상세
108
+
109
+ 단계별로 하위 절을 나눈다. 코드 시그니처, 데이터 모양, 예시 등 구체적 내용을 담는다.
110
+
111
+ ### 2-4. 영향 파일
112
+
113
+ **실제로 손댈 파일을 사전에 나열하는 것이 이 문서의 값이다.** 이 절을 못 채우면 아직 계획이 덜 선 것이다.
114
+
115
+ ### 2-5. 다루지 않는 항목
116
+
117
+ 후보로 올랐다가 빠진 것을 **처리와 이유와 함께** 적는다. 이게 없으면 같은 논의가 반복된다.
118
+
119
+ ### 2-6. 검증 기준
120
+
121
+ 자동(테스트, 빌드, 린트)과 사용자(기능 동작, 시각 검수)를 나눈다.
122
+
123
+ ### 2-7. 예상 산출물
124
+
125
+ 코드 변경이 기존 문서에 영향을 주면, 어느 문서의 어느 절을 갱신할지 미리 적어둔다.
126
+
127
+ ### 2-8. 결정은 본문에 녹인다
128
+
129
+ 결정을 누적하는 별도 절은 append만 쌓이고 갱신되지 않아, 읽을 정보와 잡음이 뒤섞인다.
130
+
131
+ - 결정의 **결과**는 해당 절 본문에 현재 상태로 반영한다
132
+ - 결정이 있었다는 **사건**은 변경 이력에 남긴다
133
+
134
+ ### 2-9. 꼬리 절
135
+
136
+ | 절 | 규칙 |
137
+ |---|-----|
138
+ | 참조 | 본문 링크를 모아 기계가 채운다 |
139
+ | 미확정 사항 | 마커 기반 생성 뷰 |
140
+ | 변경 이력 | 한 커밋이 한 줄 |
141
+
142
+ ## 참조
143
+
144
+ ### 문서
145
+
146
+ - [`spec.md`](./spec.md)
147
+
148
+ ### 코드·데이터
149
+
150
+ 해당 없음 - 템플릿 문서.
151
+
152
+ ## 미확정 사항
153
+
154
+ 해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([`pending.md`](../../specthread/pending.md)).
155
+
156
+ ## 변경 이력
157
+
158
+ | 날짜 | 내용 |
159
+ |-----|-----|