specthread 0.2.1 → 0.2.3
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.
- package/README.md +82 -191
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,8 +1,14 @@
|
|
|
1
1
|
# specthread
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/specthread) [](https://github.com/dingPie/specthread/blob/main/LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
스펙 문서에 현재 상태만 남기고, 그 규칙을 코드로 검사하는 Spec-Driven Development(SDD) 도구입니다.
|
|
6
|
+
|
|
7
|
+
- **현재 상태만 담는 스펙**: 정하지 못한 것은 `pending.md` 로, 지난 이력은 변경 이력과 git 으로 분리. 이 원칙을 14개 규칙으로 검사
|
|
8
|
+
- **코드로 하는 검사**: 목차·참조 절은 자동 생성하고, 링크·절 참조를 포함한 30개 규칙을 검사. CI 에서 종료 코드로 판정
|
|
9
|
+
- **기본 작업 흐름**: spec·plan 템플릿과 AI 에이전트용 `AGENTS.md`·스킬로 계획 → 구현 → spec 반영
|
|
10
|
+
|
|
11
|
+
<br />
|
|
6
12
|
|
|
7
13
|
## 시작하기
|
|
8
14
|
|
|
@@ -12,237 +18,122 @@ npx specthread init
|
|
|
12
18
|
npx specthread check
|
|
13
19
|
```
|
|
14
20
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
## init 이 만드는 파일
|
|
21
|
+
`init` 이 규칙 문서, 설정, AI 도구용 파일을 만들고 `check` 가 문서를 검사합니다. 지적은 파일과 줄 번호, 규칙 ID 와 함께 출력됩니다.
|
|
18
22
|
|
|
19
23
|
```
|
|
20
|
-
|
|
21
|
-
config.jsonc 설정
|
|
22
|
-
rules.md 문서 형식 규칙
|
|
23
|
-
project.md 설정값의 맥락과 근거
|
|
24
|
-
pending.md 미확정 사항 정본
|
|
25
|
-
templates/ 문서 골격 (검사 대상 아님)
|
|
26
|
-
spec.md
|
|
27
|
-
plan.md
|
|
28
|
-
AGENTS.md AI 도구 진입점
|
|
29
|
-
CLAUDE.md Claude Code 용 (@AGENTS.md)
|
|
30
|
-
.claude/skills/ Claude Code 스킬
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
기존 `AGENTS.md` 가 있으면 `<!-- specthread:start -->` 와 `<!-- specthread:end -->` 표식 사이에만 specthread 섹션을 넣습니다. 기존 `CLAUDE.md` 에는 `@AGENTS.md` 줄만 추가하고, `.gitignore` 에는 개인 설정 파일 경로를 추가합니다.
|
|
34
|
-
|
|
35
|
-
| 종류 | 파일 | `init` | `init --force` |
|
|
36
|
-
| ---- | ---- | ------ | -------------- |
|
|
37
|
-
| 패키지 파일 | `rules.md`, `templates/`, `.claude/skills/` | 없을 때만 생성 | 새 버전으로 덮어씀 |
|
|
38
|
-
| 사용자 파일 | `config.jsonc`, `project.md`, `pending.md` | 없을 때만 생성 | 유지 |
|
|
39
|
-
| 병합 | `AGENTS.md`(표식 사이), `CLAUDE.md`, `.gitignore` | 병합 | 병합 |
|
|
24
|
+
지적 4 건
|
|
40
25
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
npx specthread init [--tools claude,cursor] # 프로젝트 초기화
|
|
47
|
-
npx specthread init --force # 패키지 파일 갱신, 업데이트 프롬프트 출력
|
|
48
|
-
npx specthread check # 문서 정합성 검사
|
|
49
|
-
npx specthread gen # 생성 결과 미리보기
|
|
50
|
-
npx specthread gen --write # 생성 결과 적용
|
|
26
|
+
docs/spec/auth.md
|
|
27
|
+
3 toc/stale 목차가 헤딩과 어긋난다 - 항목 2 / 헤딩 3
|
|
28
|
+
10 link/target 대상이 없다 - ./session.md
|
|
29
|
+
14 section-ref/unknown-doc §3 없는 문서를 가리킨다 - api.md
|
|
30
|
+
20 reference/missing 참조 절이 없다 - 본문 링크 1 대상
|
|
51
31
|
```
|
|
52
32
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
30개 규칙으로 문서 형식을 검사합니다. 하위 디렉터리에서 실행해도 `specthread/config.jsonc` 가 있는 디렉터리를 루트로 삼아 같은 범위를 검사합니다.
|
|
56
|
-
|
|
57
|
-
| 종료 코드 | 의미 |
|
|
58
|
-
| --------- | ---- |
|
|
59
|
-
| 0 | 지적 없음 |
|
|
60
|
-
| 1 | 지적 있음 |
|
|
61
|
-
| 2 | 실행 실패 (설정 파일 없음, 설정 오류, 모르는 명령) |
|
|
62
|
-
|
|
63
|
-
### gen
|
|
64
|
-
|
|
65
|
-
본문 링크, 헤딩, `pending.md` 항목에서 아래 내용을 생성합니다. `--write` 없이 실행하면 바뀔 파일 목록만 출력합니다.
|
|
66
|
-
|
|
67
|
-
| 생성 대상 | 내용 | 조건 |
|
|
68
|
-
| --------- | ---- | ---- |
|
|
69
|
-
| 목차 | 제목 아래 `##` 헤딩 목록 | 항상 |
|
|
70
|
-
| 참조 절 | 본문 링크를 대상별로 모은 `## 참조` | `features.references` |
|
|
71
|
-
| 미확정 사항 절 | `pending.md` 항목 중 그 문서를 참조하는 것 | `features.markers`, 절이 이미 있는 문서만 |
|
|
72
|
-
| 요약 표 | `pending.md` 각 절 첫 부분의 항목 표 | `features.markers` |
|
|
73
|
-
|
|
74
|
-
꼬리 절(참조 → 미확정 사항 → 변경 이력) 순서가 어긋난 문서는 생성하지 않고 건너뜁니다.
|
|
75
|
-
|
|
76
|
-
### init --force
|
|
77
|
-
|
|
78
|
-
`rules.md`, 템플릿, 스킬을 새 버전으로 바꾸고, 남은 정리를 AI 에게 맡길 업데이트 프롬프트를 출력합니다. 프롬프트에는 실행할 때 감지한 항목만 포함됩니다.
|
|
79
|
-
|
|
80
|
-
| 감지 항목 | 프롬프트 단계 |
|
|
81
|
-
| --------- | ------------- |
|
|
82
|
-
| 내용이 바뀐 패키지 파일 | git diff 로 사용자 수정분 확인 |
|
|
83
|
-
| 표식 없는 이전 형식 `AGENTS.md` | 표식으로 감싼 뒤 `init` 재실행 |
|
|
84
|
-
| 끝 표식이 없는 `AGENTS.md` | 끝 표식 추가 후 `init` 재실행 |
|
|
85
|
-
| 이전 경로의 스킬 파일 (`.claude/skills/<이름>.md`) | 새 스킬과 비교 후 삭제 |
|
|
86
|
-
| 설정 파일의 제거된 키 (주석 포함) | 키 삭제 |
|
|
87
|
-
| 사용자 파일의 옛 문구 | 현재 문구로 교체 |
|
|
88
|
-
| `path` 에서 빠진 기본 경로 | 의도 확인 |
|
|
89
|
-
|
|
90
|
-
검사(`check`)와 생성(`gen --write`) 단계는 항상 포함됩니다. Claude Code 에서 `! npx specthread init --force` 로 실행하면 출력이 대화에 바로 포함됩니다.
|
|
91
|
-
|
|
92
|
-
## 검사 규칙
|
|
93
|
-
|
|
94
|
-
규칙 ID 는 `<군>/<검사>` 형식입니다. 규칙 본문은 `specthread/rules.md` 에 있고, 각 절에 해당 규칙 ID 가 적혀 있습니다.
|
|
95
|
-
|
|
96
|
-
| 군 | 수 | 검사 내용 |
|
|
97
|
-
| -- | -- | --------- |
|
|
98
|
-
| `heading` | 4 | 제목 1개, 꼬리 절 이름·번호·순서 |
|
|
99
|
-
| `toc` | 2 | 목차 누락, 헤딩과 불일치 |
|
|
100
|
-
| `link` | 2 | 링크 대상 파일, 앵커 |
|
|
101
|
-
| `section-ref` | 5 | `§N` 대상 절 존재, 앵커 링크 사용, 문서명 해소 |
|
|
102
|
-
| `reference` | 2 | 참조 절 누락, 본문 링크와 불일치 |
|
|
103
|
-
| `changelog` | 1 | 변경 이력 날짜 순서 |
|
|
104
|
-
| `timestamp` | 1 | 본문의 날짜 |
|
|
105
|
-
| `marker` | 3 | 마커와 `pending.md` 항목 대조, 종류 등록 여부 |
|
|
106
|
-
| `pending` | 9 | 항목 형식, 시점 표기, 요약 표·미확정 사항 절 최신 여부 |
|
|
107
|
-
| `style` | 1 | 코드의 규칙 ID 가 `rules.md` 에 선언됐는지 |
|
|
108
|
-
|
|
109
|
-
검사를 끄는 방법:
|
|
110
|
-
|
|
111
|
-
- 기능 단위: `features.markers`, `features.references`
|
|
112
|
-
- 경로 단위: `skipCheck`
|
|
113
|
-
- 줄 단위: 같은 줄이나 바로 윗줄의 주석에 `@specthread-ignore`
|
|
114
|
-
|
|
115
|
-
## 설정
|
|
33
|
+
목차와 참조 절처럼 본문에서 만들 수 있는 부분은 `npx specthread gen --write` 로 고칩니다.
|
|
116
34
|
|
|
117
|
-
|
|
35
|
+
<details>
|
|
36
|
+
<summary>init 이 만드는 파일</summary>
|
|
118
37
|
|
|
119
38
|
```
|
|
120
|
-
|
|
39
|
+
specthread/
|
|
40
|
+
config.jsonc 설정
|
|
41
|
+
rules.md 문서 형식 규칙
|
|
42
|
+
project.md 설정값의 맥락과 근거
|
|
43
|
+
pending.md 미확정 사항 정본
|
|
44
|
+
templates/ spec·plan 문서 골격
|
|
45
|
+
AGENTS.md AI 도구 진입점
|
|
46
|
+
CLAUDE.md @AGENTS.md
|
|
47
|
+
.claude/skills/ Claude Code 스킬
|
|
121
48
|
```
|
|
122
49
|
|
|
123
|
-
|
|
124
|
-
- 그 밖의 객체: 키 단위 병합
|
|
125
|
-
- 잘못된 값: 파일과 키를 출력하고 종료 코드 2
|
|
126
|
-
- 제거된 키, 모르는 키: 경고만 출력
|
|
50
|
+
기존 `AGENTS.md`, `CLAUDE.md` 가 있으면 specthread 내용만 추가합니다.
|
|
127
51
|
|
|
128
|
-
|
|
129
|
-
| -- | ---- | ------ |
|
|
130
|
-
| `path` | 스캔 대상 경로 (키는 자유 라벨) | `docs/`, `specthread/` |
|
|
131
|
-
| `fileKinds` | 확장자별 파일 종류 (`doc` / `source`) | `doc` 은 `.md`, `source` 는 코드·데이터 확장자 |
|
|
132
|
-
| `features` | 기능 켜기·끄기 (`markers`, `references`) | 모두 `true` |
|
|
133
|
-
| `markers` | 마커 종류(`types`), 해결 예정 라벨(`timepoints`) | `["system"]`, `[]` |
|
|
134
|
-
| `ignoreDocNames` | 절 참조 해소에서 제외할 문서 이름 | `[]` |
|
|
135
|
-
| `skipCheck` | 검사·생성을 건너뛸 경로 | `[]` |
|
|
136
|
-
| `skipRefs` | 참조 절을 만들지 않을 경로 | `[]` |
|
|
137
|
-
| `work` | 작업 문서 폴더 | `docs/work/` |
|
|
52
|
+
</details>
|
|
138
53
|
|
|
139
|
-
|
|
54
|
+
새 버전으로 올릴 때는 패키지를 갱신하고 `init --force` 를 실행합니다. 규칙·템플릿·스킬만 새 버전으로 바뀌고, 남은 정리를 위한 프롬프트가 출력됩니다. 이 프롬프트를 AI 에게 그대로 전달하면 됩니다.
|
|
140
55
|
|
|
141
|
-
|
|
56
|
+
```bash
|
|
57
|
+
npm install -D specthread@latest
|
|
58
|
+
npx specthread init --force
|
|
59
|
+
```
|
|
142
60
|
|
|
143
|
-
|
|
61
|
+
<br />
|
|
144
62
|
|
|
145
|
-
|
|
63
|
+
## 명령어
|
|
146
64
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
65
|
+
```bash
|
|
66
|
+
npx specthread init # 프로젝트 초기화
|
|
67
|
+
npx specthread init --force # 새 버전으로 갱신
|
|
68
|
+
npx specthread check # 문서 검사
|
|
69
|
+
npx specthread gen # 생성 결과 미리보기
|
|
70
|
+
npx specthread gen --write # 생성 결과 적용
|
|
71
|
+
```
|
|
152
72
|
|
|
153
|
-
|
|
73
|
+
- `check`: 지적이 있으면 종료 코드 1, 설정을 읽지 못하면 2
|
|
74
|
+
- `gen`: 목차, 참조 절, 미확정 사항 목록 생성. `--write` 없이는 바뀔 파일 목록만 출력
|
|
75
|
+
- `init --force`: `config.jsonc`, `project.md`, `pending.md` 는 덮어쓰지 않음
|
|
154
76
|
|
|
155
|
-
|
|
77
|
+
규칙 전체와 규칙 ID 는 [`rules.md`](https://github.com/dingPie/specthread/blob/main/scaffold/rules.md) 에 있습니다. `init` 이 같은 파일을 `specthread/rules.md` 로 설치합니다.
|
|
156
78
|
|
|
157
|
-
|
|
158
|
-
| ---- | ---- | ---- |
|
|
159
|
-
| 코드·문서의 발생 지점 | `PENDING::<종류>::<slug>` | 사람 |
|
|
160
|
-
| `specthread/pending.md` | `` ### `[<종류>::<slug>]` 제목 `` | 사람 |
|
|
161
|
-
| 각 문서의 `## 미확정 사항` | 그 문서를 참조하는 항목 목록 | `gen` |
|
|
79
|
+
<br />
|
|
162
80
|
|
|
163
|
-
|
|
81
|
+
## 작업 흐름
|
|
164
82
|
|
|
165
|
-
|
|
83
|
+
구현 전에 spec 을 읽고, 구현 후에 spec 을 갱신합니다. 진행 중 정하지 못한 것은 `PENDING::<종류>::<slug>` 마커로 남기고 작업을 계속합니다.
|
|
166
84
|
|
|
167
85
|
```
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
구현 전에 spec 을 읽고, 구현 후에 spec 을 갱신합니다. 작업 계획은 `docs/work/` 에 plan 문서로 작성하고, 작업이 끝나면 내용을 spec 에 반영한 뒤 plan 문서를 삭제합니다.
|
|
172
|
-
|
|
173
|
-
### 예시: 기존 인증 spec 에 소셜 로그인 추가
|
|
86
|
+
You: 소셜 로그인 계획 세워줘
|
|
87
|
+
AI: docs/spec/auth.md 확인 후
|
|
88
|
+
docs/work/social-login.md 작성
|
|
174
89
|
|
|
175
|
-
`docs/spec/auth.md` 가 있는 프로젝트에서 소셜 로그인을 추가하는 경우입니다.
|
|
176
|
-
|
|
177
|
-
```
|
|
178
|
-
You: 소셜 로그인 기능 계획 세워줘
|
|
179
|
-
AI: docs/spec/auth.md 확인 후 plan 템플릿으로 docs/work/social-login.md 작성.
|
|
180
|
-
목표, 작업 단계, 영향 파일 포함.
|
|
181
|
-
문서 정합성 검사 통과.
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
```
|
|
185
90
|
You: 진행해줘
|
|
186
|
-
AI:
|
|
187
|
-
|
|
188
|
-
단계 상태를 "완료"로 갱신.
|
|
189
|
-
```
|
|
91
|
+
AI: OAuth 연동 구현, 세션 방식은 미정이라
|
|
92
|
+
PENDING::design::oauth-session 마커 추가
|
|
190
93
|
|
|
94
|
+
You: 정리해줘
|
|
95
|
+
AI: 작업 내용을 docs/spec/auth.md 에 반영,
|
|
96
|
+
계획 문서 삭제, check 통과
|
|
191
97
|
```
|
|
192
|
-
You: 전부 끝났어, 정리해줘
|
|
193
|
-
AI: 종료 게이트 점검 후 작업 내용을 docs/spec/auth.md §3 에 반영.
|
|
194
|
-
docs/work/social-login.md 삭제.
|
|
195
|
-
문서 정합성 검사 통과.
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
작업이 끝나면 `docs/spec/auth.md` 에 소셜 로그인 절이 추가되고 plan 문서는 삭제됩니다. spec 은 항상 현재 시스템을 설명하는 정본으로 유지됩니다.
|
|
199
|
-
|
|
200
|
-
## AI 도구 지원
|
|
201
|
-
|
|
202
|
-
`AGENTS.md` 가 AI 도구의 진입점입니다. 대부분의 AI 코딩 도구가 이 파일을 읽습니다.
|
|
203
98
|
|
|
204
|
-
|
|
205
|
-
| ---- | ---- |
|
|
206
|
-
| Claude Code | `CLAUDE.md` 의 `@AGENTS.md` 로 읽음 |
|
|
207
|
-
| Cursor / Copilot / Codex / Gemini | `AGENTS.md` 를 직접 읽음 |
|
|
99
|
+
Claude Code 에서는 아래 스킬로 같은 흐름을 실행합니다. 스킬 없이 자연어로 요청해도 `AGENTS.md` 에 적힌 흐름대로 진행합니다.
|
|
208
100
|
|
|
209
|
-
|
|
101
|
+
- `/plan-open`: 작업 계획 문서 작성·확정
|
|
102
|
+
- `/plan-run`: 계획에 따른 구현과 기록
|
|
103
|
+
- `/plan-close`: 완료된 작업을 spec 에 반영
|
|
104
|
+
- `/check`, `/gen`: 검사·생성 실행과 결과 안내
|
|
210
105
|
|
|
211
|
-
|
|
212
|
-
| ---- | ---- |
|
|
213
|
-
| `/check` | 문서 검사 실행, 결과 해석 |
|
|
214
|
-
| `/gen` | 생성 결과 미리보기, 승인 후 적용 |
|
|
215
|
-
| `/plan-open` | 작업 계획 문서 작성·검수·확정 |
|
|
216
|
-
| `/plan-run` | 계획에 따른 실행과 기록 |
|
|
217
|
-
| `/plan-close` | 완료된 작업을 spec 에 반영, plan 문서 삭제 |
|
|
106
|
+
Cursor, Copilot, Codex, Gemini 는 `AGENTS.md` 를 직접 읽습니다. 스킬이 필요 없으면 `init --tools cursor` 처럼 `claude` 를 빼고 실행합니다.
|
|
218
107
|
|
|
219
|
-
|
|
108
|
+
<br />
|
|
220
109
|
|
|
221
|
-
##
|
|
110
|
+
## 설정
|
|
222
111
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
112
|
+
`specthread/config.jsonc` 에서 스캔 경로, 파일 종류, 마커 종류 등을 정합니다. `init` 이 만든 파일에 모든 옵션이 주석으로 설명되어 있습니다.
|
|
113
|
+
|
|
114
|
+
```jsonc
|
|
115
|
+
{
|
|
116
|
+
"path": {
|
|
117
|
+
"docs": ["docs/"],
|
|
118
|
+
"source": ["src/"]
|
|
119
|
+
},
|
|
120
|
+
"markers": {
|
|
121
|
+
"types": ["system", "design"]
|
|
122
|
+
}
|
|
123
|
+
}
|
|
226
124
|
```
|
|
227
125
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
### 0.2.0 에서 바뀐 동작
|
|
126
|
+
`path` 는 기본값과 합치지 않고 교체되므로 `docs/` 도 함께 적습니다. 개인 설정은 `specthread/config.local.jsonc` 에 둡니다.
|
|
231
127
|
|
|
232
|
-
|
|
233
|
-
| ---- | ---- |
|
|
234
|
-
| `locale`, `rules`, `pending`, `project`, `features.emDash` 키 제거 | 남아 있으면 경고만 출력 |
|
|
235
|
-
| `path` 통째 교체 | 일부 키만 적으면 기본 `docs/`, `specthread/` 스캔이 빠짐 |
|
|
236
|
-
| 종료 코드 2 | 설정 파일이 없거나 읽지 못할 때, 모르는 명령일 때 |
|
|
237
|
-
| 규칙 추가 | `heading/tail-order`, `marker/unknown-type`, `pending/unknown-timepoint` |
|
|
238
|
-
| em dash 검사 제거 | `style/em-dash` 없음 |
|
|
239
|
-
| 스킬 경로 | `.claude/skills/<이름>/SKILL.md`. 옛 파일은 지우지 않고 안내 |
|
|
128
|
+
<br />
|
|
240
129
|
|
|
241
130
|
## 요구 사항
|
|
242
131
|
|
|
243
132
|
- Node.js 18 이상
|
|
244
133
|
- 외부 의존성 없음
|
|
245
134
|
|
|
135
|
+
<br />
|
|
136
|
+
|
|
246
137
|
## 라이선스
|
|
247
138
|
|
|
248
139
|
MIT
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specthread",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.3",
|
|
4
|
+
"description": "스펙 문서에 현재 상태만 남기고 코드로 검사하는 SDD 도구",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"specthread": "./dist/bin/cli.js"
|