specthread 0.2.0 → 0.2.1
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 +153 -123
- package/dist/bin/cli.js +2 -1
- package/dist/checks/headings.js +2 -2
- package/dist/checks/pending.js +3 -1
- package/dist/checks/sections.js +0 -1
- package/dist/checks/timestamps.js +1 -1
- package/dist/commands/init.js +51 -27
- package/dist/commands/upgrade-prompt.d.ts +12 -0
- package/dist/commands/upgrade-prompt.js +147 -0
- package/dist/config-loader.d.ts +22 -0
- package/dist/config-loader.js +41 -25
- package/dist/constants/docs.d.ts +1 -2
- package/dist/constants/docs.js +1 -2
- package/dist/constants/patterns.d.ts +1 -3
- package/dist/constants/patterns.js +1 -3
- package/dist/gen/pending-section.js +2 -2
- package/dist/gen/references.js +4 -4
- package/dist/gen/summary.js +2 -1
- package/dist/gen/toc.js +1 -1
- package/dist/types.d.ts +2 -2
- package/dist/utils/anchor.d.ts +1 -1
- package/dist/utils/anchor.js +1 -1
- package/dist/utils/ignore.js +1 -1
- package/dist/utils/parse.d.ts +6 -6
- package/dist/utils/parse.js +7 -8
- package/dist/utils/resolve.d.ts +15 -5
- package/dist/utils/resolve.js +49 -25
- package/dist/utils/scan.js +6 -2
- package/package.json +2 -2
- package/scaffold/claude/skills/gen/SKILL.md +2 -2
package/README.md
CHANGED
|
@@ -1,86 +1,166 @@
|
|
|
1
1
|
# specthread
|
|
2
2
|
|
|
3
|
-
Spec-Driven Development
|
|
3
|
+
Spec-Driven Development(SDD) 도구입니다. 문서를 단일 정본으로 관리하고, 문서 형식 규칙과 그 규칙을 검사·생성하는 도구를 함께 제공합니다.
|
|
4
|
+
|
|
5
|
+
AI 와 함께 코드를 작성하면 문서와 코드가 쉽게 어긋납니다. specthread 는 문서 형식을 규칙으로 정하고, 규칙 위반과 생성물의 불일치를 `check` 로 검출합니다. 목차·참조 절처럼 다른 내용에서 만들 수 있는 부분은 `gen` 이 생성합니다.
|
|
4
6
|
|
|
5
7
|
## 시작하기
|
|
6
8
|
|
|
7
9
|
```bash
|
|
8
|
-
npm install -
|
|
9
|
-
specthread init
|
|
10
|
-
specthread check
|
|
10
|
+
npm install -D specthread
|
|
11
|
+
npx specthread init
|
|
12
|
+
npx specthread check
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
전역으로 설치하려면 `npm install -g specthread` 후 `specthread` 로 실행합니다.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
## init 이 만드는 파일
|
|
16
18
|
|
|
17
19
|
```
|
|
18
|
-
specthread/
|
|
19
|
-
config.jsonc
|
|
20
|
-
rules.md
|
|
21
|
-
project.md
|
|
22
|
-
pending.md
|
|
23
|
-
templates/
|
|
20
|
+
specthread/
|
|
21
|
+
config.jsonc 설정
|
|
22
|
+
rules.md 문서 형식 규칙
|
|
23
|
+
project.md 설정값의 맥락과 근거
|
|
24
|
+
pending.md 미확정 사항 정본
|
|
25
|
+
templates/ 문서 골격 (검사 대상 아님)
|
|
24
26
|
spec.md
|
|
25
27
|
plan.md
|
|
26
|
-
AGENTS.md
|
|
27
|
-
CLAUDE.md
|
|
28
|
-
.claude/skills/
|
|
28
|
+
AGENTS.md AI 도구 진입점
|
|
29
|
+
CLAUDE.md Claude Code 용 (@AGENTS.md)
|
|
30
|
+
.claude/skills/ Claude Code 스킬
|
|
29
31
|
```
|
|
30
32
|
|
|
31
|
-
기존 `AGENTS.md
|
|
33
|
+
기존 `AGENTS.md` 가 있으면 `<!-- specthread:start -->` 와 `<!-- specthread:end -->` 표식 사이에만 specthread 섹션을 넣습니다. 기존 `CLAUDE.md` 에는 `@AGENTS.md` 줄만 추가하고, `.gitignore` 에는 개인 설정 파일 경로를 추가합니다.
|
|
32
34
|
|
|
33
35
|
| 종류 | 파일 | `init` | `init --force` |
|
|
34
36
|
| ---- | ---- | ------ | -------------- |
|
|
35
37
|
| 패키지 파일 | `rules.md`, `templates/`, `.claude/skills/` | 없을 때만 생성 | 새 버전으로 덮어씀 |
|
|
36
|
-
| 사용자 파일 | `config.jsonc`, `project.md`, `pending.md` | 없을 때만 생성 |
|
|
37
|
-
| 병합 | `AGENTS.md`
|
|
38
|
+
| 사용자 파일 | `config.jsonc`, `project.md`, `pending.md` | 없을 때만 생성 | 유지 |
|
|
39
|
+
| 병합 | `AGENTS.md`(표식 사이), `CLAUDE.md`, `.gitignore` | 병합 | 병합 |
|
|
38
40
|
|
|
39
|
-
설정을 처음 상태로 되돌리려면 `config.jsonc
|
|
41
|
+
설정을 처음 상태로 되돌리려면 `config.jsonc` 를 지우고 `init` 을 다시 실행합니다.
|
|
40
42
|
|
|
41
43
|
## 명령어
|
|
42
44
|
|
|
43
45
|
```bash
|
|
44
46
|
npx specthread init [--tools claude,cursor] # 프로젝트 초기화
|
|
45
|
-
npx specthread init --force # 패키지
|
|
47
|
+
npx specthread init --force # 패키지 파일 갱신, 업데이트 프롬프트 출력
|
|
46
48
|
npx specthread check # 문서 정합성 검사
|
|
47
|
-
npx specthread gen #
|
|
48
|
-
npx specthread gen --write #
|
|
49
|
+
npx specthread gen # 생성 결과 미리보기
|
|
50
|
+
npx specthread gen --write # 생성 결과 적용
|
|
49
51
|
```
|
|
50
52
|
|
|
51
53
|
### check
|
|
52
54
|
|
|
53
|
-
30개 규칙으로 문서 형식을
|
|
55
|
+
30개 규칙으로 문서 형식을 검사합니다. 하위 디렉터리에서 실행해도 `specthread/config.jsonc` 가 있는 디렉터리를 루트로 삼아 같은 범위를 검사합니다.
|
|
56
|
+
|
|
57
|
+
| 종료 코드 | 의미 |
|
|
58
|
+
| --------- | ---- |
|
|
59
|
+
| 0 | 지적 없음 |
|
|
60
|
+
| 1 | 지적 있음 |
|
|
61
|
+
| 2 | 실행 실패 (설정 파일 없음, 설정 오류, 모르는 명령) |
|
|
54
62
|
|
|
55
63
|
### gen
|
|
56
64
|
|
|
57
|
-
본문
|
|
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`
|
|
58
114
|
|
|
59
115
|
## 설정
|
|
60
116
|
|
|
61
|
-
`specthread/config.jsonc
|
|
117
|
+
`specthread/config.jsonc` 로 프로젝트별 동작을 정합니다. 개인 설정은 `specthread/config.local.jsonc` 에 두고, 이 파일은 `init` 이 `.gitignore` 에 추가합니다.
|
|
62
118
|
|
|
63
119
|
```
|
|
64
|
-
|
|
65
|
-
↓ deep merge
|
|
66
|
-
specthread/config.jsonc (프로젝트 공유)
|
|
67
|
-
↓ deep merge
|
|
68
|
-
specthread/config.local.jsonc (개인)
|
|
120
|
+
도구 기본값 → specthread/config.jsonc → specthread/config.local.jsonc
|
|
69
121
|
```
|
|
70
122
|
|
|
71
|
-
배열과 `path
|
|
123
|
+
- 배열과 `path`: 통째로 교체
|
|
124
|
+
- 그 밖의 객체: 키 단위 병합
|
|
125
|
+
- 잘못된 값: 파일과 키를 출력하고 종료 코드 2
|
|
126
|
+
- 제거된 키, 모르는 키: 경고만 출력
|
|
127
|
+
|
|
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/` |
|
|
72
138
|
|
|
73
|
-
|
|
74
|
-
| ----------- | ------------------------------------------ |
|
|
75
|
-
| `path` | 스캔 대상 경로 (자유 KV) |
|
|
76
|
-
| `fileKinds` | 확장자 → 종류 매핑 (`doc` / `source`) |
|
|
77
|
-
| `features` | 기능 플래그 (`markers`, `references`) |
|
|
78
|
-
| `markers` | 마커 종류·시점 라벨 |
|
|
79
|
-
| `skipCheck` | 검사·생성을 건너뛸 경로 |
|
|
80
|
-
| `skipRefs` | 참조 절 생성을 건너뛸 경로 |
|
|
81
|
-
| `work` | 작업 문서 폴더 (기본 `docs/work/`) |
|
|
139
|
+
`init` 이 만드는 `config.jsonc` 에 모든 옵션의 설명이 주석으로 적혀 있습니다. `fileKinds.doc` 에 확장자(예: `.mdx`)를 추가하면 그 파일도 문서로 검사하고 절 참조 대상으로 해소합니다.
|
|
82
140
|
|
|
83
|
-
`specthread/` 아래
|
|
141
|
+
`specthread/` 아래 규칙·미확정 사항·프로젝트 문서의 경로는 고정입니다. 템플릿과 설정 파일은 항상 검사에서 제외됩니다.
|
|
142
|
+
|
|
143
|
+
## 문서 체계
|
|
144
|
+
|
|
145
|
+
`specthread/rules.md` 가 문서 형식 규칙의 정본입니다. 주요 규칙은 아래와 같습니다.
|
|
146
|
+
|
|
147
|
+
- 제목 바로 아래 목차
|
|
148
|
+
- 본문 절은 `§N-M` 번호 체계, 다른 문서의 절은 앵커 링크로 참조
|
|
149
|
+
- 문서 끝 꼬리 절은 참조 → 미확정 사항 → 변경 이력 순서
|
|
150
|
+
- 날짜·버전 정보는 본문이 아닌 변경 이력에 기록
|
|
151
|
+
- 빈 섹션은 `해당 없음 - <이유>`
|
|
152
|
+
|
|
153
|
+
### 미확정 사항
|
|
154
|
+
|
|
155
|
+
작업 중 정하지 못한 것은 작업을 멈추지 않고 마커로 표시합니다. 같은 ID 를 세 곳에서 관리하고, 정본은 `pending.md` 하나입니다.
|
|
156
|
+
|
|
157
|
+
| 위치 | 표기 | 작성 |
|
|
158
|
+
| ---- | ---- | ---- |
|
|
159
|
+
| 코드·문서의 발생 지점 | `PENDING::<종류>::<slug>` | 사람 |
|
|
160
|
+
| `specthread/pending.md` | `` ### `[<종류>::<slug>]` 제목 `` | 사람 |
|
|
161
|
+
| 각 문서의 `## 미확정 사항` | 그 문서를 참조하는 항목 목록 | `gen` |
|
|
162
|
+
|
|
163
|
+
JSON 처럼 주석을 쓸 수 없는 파일에서는 `"_pending": "<종류>::<slug>"` 필드로 표기합니다. `check` 는 마커와 항목을 양방향으로 대조해서, 항목 없는 마커(`marker/orphan`)와 마커 없는 항목(`marker/unmarked`)을 지적합니다.
|
|
84
164
|
|
|
85
165
|
## SDD 작업 흐름
|
|
86
166
|
|
|
@@ -88,130 +168,80 @@ specthread/config.local.jsonc (개인)
|
|
|
88
168
|
스펙 확인 → 현황 점검(check) → 계획 수립 → 구현 → 검증(check) → 문서 갱신
|
|
89
169
|
```
|
|
90
170
|
|
|
91
|
-
구현 전에 spec을 읽고, 구현 후에 spec을
|
|
171
|
+
구현 전에 spec 을 읽고, 구현 후에 spec 을 갱신합니다. 작업 계획은 `docs/work/` 에 plan 문서로 작성하고, 작업이 끝나면 내용을 spec 에 반영한 뒤 plan 문서를 삭제합니다.
|
|
92
172
|
|
|
93
|
-
### 예시: 기존 인증 spec에 소셜 로그인 추가
|
|
173
|
+
### 예시: 기존 인증 spec 에 소셜 로그인 추가
|
|
94
174
|
|
|
95
|
-
`docs/spec/auth.md
|
|
175
|
+
`docs/spec/auth.md` 가 있는 프로젝트에서 소셜 로그인을 추가하는 경우입니다.
|
|
96
176
|
|
|
97
177
|
```
|
|
98
178
|
You: 소셜 로그인 기능 계획 세워줘
|
|
99
|
-
AI: docs/spec/auth.md
|
|
100
|
-
|
|
101
|
-
목표, 작업 단계, 영향 파일을 함께 채운다.
|
|
179
|
+
AI: docs/spec/auth.md 확인 후 plan 템플릿으로 docs/work/social-login.md 작성.
|
|
180
|
+
목표, 작업 단계, 영향 파일 포함.
|
|
102
181
|
문서 정합성 검사 통과.
|
|
103
182
|
```
|
|
104
183
|
|
|
105
184
|
```
|
|
106
185
|
You: 진행해줘
|
|
107
186
|
AI: 작업 단계 1 "OAuth 프로바이더 연동" 구현.
|
|
108
|
-
세션 관리 방식이
|
|
109
|
-
PENDING::design::oauth-session 마커를 남긴다.
|
|
187
|
+
세션 관리 방식이 미정이라 PENDING::design::oauth-session 마커 추가.
|
|
110
188
|
단계 상태를 "완료"로 갱신.
|
|
111
189
|
```
|
|
112
190
|
|
|
113
191
|
```
|
|
114
192
|
You: 전부 끝났어, 정리해줘
|
|
115
|
-
AI: 종료 게이트 점검
|
|
116
|
-
작업 내용을 docs/spec/auth.md §3 에 흡수.
|
|
193
|
+
AI: 종료 게이트 점검 후 작업 내용을 docs/spec/auth.md §3 에 반영.
|
|
117
194
|
docs/work/social-login.md 삭제.
|
|
118
195
|
문서 정합성 검사 통과.
|
|
119
196
|
```
|
|
120
197
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
AI는 작업 중에 `check`와 `gen`을 자동으로 호출한다. `AGENTS.md`가 이 워크플로우를 AI에게 전달하고, `check`가 문서와 코드의 어긋남을 잡는다.
|
|
198
|
+
작업이 끝나면 `docs/spec/auth.md` 에 소셜 로그인 절이 추가되고 plan 문서는 삭제됩니다. spec 은 항상 현재 시스템을 설명하는 정본으로 유지됩니다.
|
|
124
199
|
|
|
125
200
|
## AI 도구 지원
|
|
126
201
|
|
|
127
|
-
`AGENTS.md
|
|
128
|
-
|
|
129
|
-
| 도구 | 동작 |
|
|
130
|
-
| --------------------------------- | -------------------------------------- |
|
|
131
|
-
| Claude Code | `CLAUDE.md`의 `@AGENTS.md`가 자동 확장 |
|
|
132
|
-
| Cursor / Copilot / Codex / Gemini | `AGENTS.md`를 네이티브로 읽음 |
|
|
202
|
+
`AGENTS.md` 가 AI 도구의 진입점입니다. 대부분의 AI 코딩 도구가 이 파일을 읽습니다.
|
|
133
203
|
|
|
134
|
-
|
|
204
|
+
| 도구 | 동작 |
|
|
205
|
+
| ---- | ---- |
|
|
206
|
+
| Claude Code | `CLAUDE.md` 의 `@AGENTS.md` 로 읽음 |
|
|
207
|
+
| Cursor / Copilot / Codex / Gemini | `AGENTS.md` 를 직접 읽음 |
|
|
135
208
|
|
|
136
|
-
|
|
137
|
-
| ------------- | ----------------------------- |
|
|
138
|
-
| `/check` | 문서 검사 실행 + 결과 해석 |
|
|
139
|
-
| `/gen` | 참조 절·목차 생성 + 적용 안내 |
|
|
140
|
-
| `/plan-open` | 작업 계획 문서 작성·검수·확정 |
|
|
141
|
-
| `/plan-run` | 계획에 따라 실행·기록 |
|
|
142
|
-
| `/plan-close` | 완료된 작업을 spec에 흡수 |
|
|
209
|
+
`--tools claude`(기본값)로 init 하면 Claude Code 스킬이 함께 설치됩니다.
|
|
143
210
|
|
|
144
|
-
스킬
|
|
211
|
+
| 스킬 | 역할 |
|
|
212
|
+
| ---- | ---- |
|
|
213
|
+
| `/check` | 문서 검사 실행, 결과 해석 |
|
|
214
|
+
| `/gen` | 생성 결과 미리보기, 승인 후 적용 |
|
|
215
|
+
| `/plan-open` | 작업 계획 문서 작성·검수·확정 |
|
|
216
|
+
| `/plan-run` | 계획에 따른 실행과 기록 |
|
|
217
|
+
| `/plan-close` | 완료된 작업을 spec 에 반영, plan 문서 삭제 |
|
|
145
218
|
|
|
146
|
-
|
|
219
|
+
스킬 없이 자연어로 요청해도 됩니다. `AGENTS.md` 에 작업 흐름이 적혀 있어서 AI 가 같은 순서로 진행합니다.
|
|
147
220
|
|
|
148
|
-
|
|
221
|
+
## 버전 올리기
|
|
149
222
|
|
|
150
223
|
```bash
|
|
151
224
|
npm install -D specthread@latest
|
|
152
225
|
npx specthread init --force
|
|
153
226
|
```
|
|
154
227
|
|
|
155
|
-
`init --force` 는
|
|
156
|
-
|
|
157
|
-
```
|
|
158
|
-
specthread 를 0.2.0 으로 올렸다. 아래를 순서대로 처리해줘.
|
|
159
|
-
내가 직접 쓴 내용은 지우지 말고, 판단이 필요하면 멈추고 물어봐.
|
|
160
|
-
|
|
161
|
-
0. specthread/rules.md 와 specthread/templates/ 를 고쳐 쓴 적이 있으면,
|
|
162
|
-
다음 단계에서 덮어써지므로 먼저 커밋되어 있는지 확인한다.
|
|
163
|
-
|
|
164
|
-
1. AGENTS.md
|
|
165
|
-
- `<!-- specthread:start -->` 표식이 없으면, specthread 가 만든 부분
|
|
166
|
-
(`# specthread` 제목부터 그 섹션 끝까지)을 `<!-- specthread:start -->` 와
|
|
167
|
-
`<!-- specthread:end -->` 로 감싼다. 그 밖의 내용은 그대로 둔다.
|
|
168
|
-
- specthread 섹션이 두 번 들어가 있으면 뒤의 것을 지운다.
|
|
169
|
-
|
|
170
|
-
2. `npx specthread init --force` 를 실행한다.
|
|
171
|
-
rules.md, 템플릿, 스킬, AGENTS.md 의 specthread 섹션이 새 버전으로 바뀐다.
|
|
172
|
-
|
|
173
|
-
3. specthread/config.jsonc
|
|
174
|
-
- `"emDash"` 키와 그 주석을 지운다.
|
|
175
|
-
- 주석으로만 남은 `locale`, `rules`, `pending`, `project` 블록을 지운다.
|
|
176
|
-
- `rules`·`pending`·`project` 에 실제 값을 적어 쓰고 있었다면 지우지 말고 알려줘.
|
|
177
|
-
이제 경로가 specthread/ 아래로 고정이라 파일을 옮겨야 한다.
|
|
178
|
-
- `path` 에 일부 키만 적어 두었다면 알려줘. 이제 path 는 기본값과 합치지 않고
|
|
179
|
-
통째로 교체되므로, docs/ 와 specthread/ 스캔이 빠질 수 있다.
|
|
180
|
-
|
|
181
|
-
4. specthread/project.md 의 "`config.jsonc` 에서 경로를 override 할 수 있다" 를
|
|
182
|
-
"경로는 `specthread/pending.md` 고정이다" 로 바꾼다.
|
|
183
|
-
|
|
184
|
-
5. specthread/pending.md 의 "종류마다 `##` 섹션이 하나씩 생긴다. 종류 값은
|
|
185
|
-
`config.markers.types` 가 정의하며" 를 "종류마다 `##` 섹션을 하나씩 둔다.
|
|
186
|
-
섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다." 로 바꾼다.
|
|
187
|
-
|
|
188
|
-
6. `.claude/skills/` 바로 아래에 check.md, gen.md, plan-open.md, plan-run.md,
|
|
189
|
-
plan-close.md 가 남아 있으면 같은 이름의 `<이름>/SKILL.md` 와 비교한다.
|
|
190
|
-
내가 고친 부분이 없으면 지우고, 있으면 알려줘.
|
|
191
|
-
|
|
192
|
-
7. `npx specthread check` 를 실행한다.
|
|
193
|
-
- `marker/unknown-type` 이 나오면 쓰고 있는 종류를 `config.markers.types` 에
|
|
194
|
-
추가할지 물어봐.
|
|
195
|
-
- `heading/tail-order` 가 나오면 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴다.
|
|
196
|
-
|
|
197
|
-
8. `npx specthread gen --write` 후 `npx specthread check` 가 0 건인지 확인한다.
|
|
198
|
-
```
|
|
228
|
+
출력된 업데이트 프롬프트를 AI 에게 전달하면 AI 가 남은 정리를 진행합니다. `init --force` 는 패키지 파일만 바꾸고 사용자 파일은 그대로 둡니다. `rules.md` 나 템플릿을 직접 고쳐 썼다면, 실행 전에 커밋해 두어야 바뀐 내용을 diff 로 확인할 수 있습니다.
|
|
199
229
|
|
|
200
|
-
바뀐
|
|
230
|
+
### 0.2.0 에서 바뀐 동작
|
|
201
231
|
|
|
202
232
|
| 변경 | 영향 |
|
|
203
233
|
| ---- | ---- |
|
|
204
|
-
| `locale`, `rules`, `pending`, `project`, `features.emDash` 키 제거 | 남아 있으면 경고만
|
|
205
|
-
| `path` 통째 교체 | 일부 키만
|
|
206
|
-
| 종료 코드 2 | 설정 파일이 없거나
|
|
234
|
+
| `locale`, `rules`, `pending`, `project`, `features.emDash` 키 제거 | 남아 있으면 경고만 출력 |
|
|
235
|
+
| `path` 통째 교체 | 일부 키만 적으면 기본 `docs/`, `specthread/` 스캔이 빠짐 |
|
|
236
|
+
| 종료 코드 2 | 설정 파일이 없거나 읽지 못할 때, 모르는 명령일 때 |
|
|
207
237
|
| 규칙 추가 | `heading/tail-order`, `marker/unknown-type`, `pending/unknown-timepoint` |
|
|
208
|
-
| em dash 검사 제거 | `style/em-dash`
|
|
209
|
-
| 스킬 경로 | `.claude/skills/<이름>/SKILL.md
|
|
238
|
+
| em dash 검사 제거 | `style/em-dash` 없음 |
|
|
239
|
+
| 스킬 경로 | `.claude/skills/<이름>/SKILL.md`. 옛 파일은 지우지 않고 안내 |
|
|
210
240
|
|
|
211
241
|
## 요구 사항
|
|
212
242
|
|
|
213
|
-
- Node.js
|
|
214
|
-
- 외부 의존성 없음
|
|
243
|
+
- Node.js 18 이상
|
|
244
|
+
- 외부 의존성 없음
|
|
215
245
|
|
|
216
246
|
## 라이선스
|
|
217
247
|
|
package/dist/bin/cli.js
CHANGED
|
@@ -7,7 +7,8 @@ const usage = `specthread - Spec-Driven Development (SDD) 도구
|
|
|
7
7
|
|
|
8
8
|
commands:
|
|
9
9
|
init [--tools claude,cursor] 프로젝트에 SDD 체계 초기화
|
|
10
|
-
init --force 패키지 파일(rules·템플릿·스킬)을 새 버전으로
|
|
10
|
+
init --force 패키지 파일(rules·템플릿·스킬)을 새 버전으로 갱신하고
|
|
11
|
+
남은 정리를 위한 업데이트 프롬프트 출력
|
|
11
12
|
check 문서 정합성 검사 (30개 규칙)
|
|
12
13
|
gen [--write] 참조 절·목차·미확정 사항 요약 생성
|
|
13
14
|
help 이 도움말 표시
|
package/dist/checks/headings.js
CHANGED
|
@@ -4,8 +4,8 @@ import { RULE } from '../constants/rules.js';
|
|
|
4
4
|
* 헤딩 구조 - 제목이 하나인가, 꼬리 절 이름을 본문에서 재사용하지 않는가,
|
|
5
5
|
* 꼬리 절에 번호가 붙지 않았는가, 꼬리 절이 정해진 순서인가.
|
|
6
6
|
*
|
|
7
|
-
*
|
|
8
|
-
* 이름이 겹치면 어느 쪽이
|
|
7
|
+
* 하나라도 어긋나면 생성기가 목차와 꼬리 절을 넣을 위치를 정할 수 없다. 꼬리 절은 이름으로 찾으므로
|
|
8
|
+
* 이름이 겹치면 어느 쪽이 꼬리 절인지 구분할 수 없고, 번호가 붙으면 규칙 8 과 어긋난다.
|
|
9
9
|
*/
|
|
10
10
|
import { isDoc, tailOrderOk, titleHeadings } from "../utils/scope.js";
|
|
11
11
|
export const checkHeadings = (index) => {
|
package/dist/checks/pending.js
CHANGED
|
@@ -11,6 +11,7 @@ import { ITEM_AS_LI, ITEM_HEADING, timepointGlobal } from '../constants/patterns
|
|
|
11
11
|
import { RULE } from '../constants/rules.js';
|
|
12
12
|
import { summaryBlocks } from '../gen/summary.js';
|
|
13
13
|
import { invertByTarget, pendingSectionBlock } from '../gen/pending-section.js';
|
|
14
|
+
import { eachContentLine } from '../utils/parse.js';
|
|
14
15
|
import { underPath } from '../utils/path-match.js';
|
|
15
16
|
import { inChangeLog, isWorkDoc } from '../utils/scope.js';
|
|
16
17
|
/**
|
|
@@ -216,7 +217,8 @@ export const checkPending = (index) => {
|
|
|
216
217
|
if (file === undefined)
|
|
217
218
|
return [];
|
|
218
219
|
const findings = [];
|
|
219
|
-
|
|
220
|
+
// 코드블록 안은 항목 형식을 보여주는 예시다
|
|
221
|
+
eachContentLine(file.lines, (raw, i) => {
|
|
220
222
|
const line = i + 1;
|
|
221
223
|
if (inChangeLog(file, line))
|
|
222
224
|
return;
|
package/dist/checks/sections.js
CHANGED
|
@@ -7,7 +7,6 @@ import { RULE } from '../constants/rules.js';
|
|
|
7
7
|
*/
|
|
8
8
|
import { basename, dirname, relative } from "node:path";
|
|
9
9
|
import { inChangeLog, inPendingSection, inRefSection, inToc, isHeadingLine, } from "../utils/scope.js";
|
|
10
|
-
/** 미해소 사유별 메시지 */
|
|
11
10
|
/**
|
|
12
11
|
* 해소 실패 사유마다 규칙 id 와 메시지.
|
|
13
12
|
*
|
|
@@ -28,7 +28,7 @@ export const checkTimestamps = (index) => {
|
|
|
28
28
|
return;
|
|
29
29
|
}
|
|
30
30
|
const line = i + 1;
|
|
31
|
-
//
|
|
31
|
+
// 코드블록은 예시, 변경 이력은 날짜가 있어야 하는 곳, 목차·미확정 사항 절은 생성물이다
|
|
32
32
|
if (fence || inChangeLog(file, line) || inToc(file, line) || inPendingSection(file, line))
|
|
33
33
|
return;
|
|
34
34
|
const mask = codeSpanMask(text);
|
package/dist/commands/init.js
CHANGED
|
@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
|
|
|
4
4
|
import { DEFAULT_CONFIG } from "../config.schema.js";
|
|
5
5
|
import { CONFIG_PATH, LOCAL_CONFIG_PATH, PENDING_PATH, PROJECT_PATH, RULES_PATH, SPECTHREAD_DIR, TEMPLATES_DIR, } from "../constants/paths.js";
|
|
6
6
|
import { renderConfig } from "./config-template.js";
|
|
7
|
+
import { renderUpgradePrompt } from "./upgrade-prompt.js";
|
|
7
8
|
const SPECTHREAD_START = "<!-- specthread:start -->";
|
|
8
9
|
const SPECTHREAD_END = "<!-- specthread:end -->";
|
|
9
10
|
const scaffoldDir = () => {
|
|
@@ -26,6 +27,8 @@ const putFile = (dest, content, force, owner) => {
|
|
|
26
27
|
return force ? "kept" : "skipped";
|
|
27
28
|
if (existed && !force)
|
|
28
29
|
return "skipped";
|
|
30
|
+
if (existed && readFileSync(dest, "utf8") === content)
|
|
31
|
+
return "unchanged";
|
|
29
32
|
const dir = dirname(dest);
|
|
30
33
|
if (!existsSync(dir))
|
|
31
34
|
mkdirSync(dir, { recursive: true });
|
|
@@ -42,30 +45,36 @@ const wrapSection = (section) => `${SPECTHREAD_START}\n${section}\n${SPECTHREAD_
|
|
|
42
45
|
* 사라질 수 있다. 그래서 건드리지 않고 알린다.
|
|
43
46
|
*/
|
|
44
47
|
const isLegacyAgents = (content) => /^# specthread\s*$/m.test(content) && /^## 2\. SDD 작업 흐름\s*$/m.test(content);
|
|
45
|
-
/** AGENTS.md 의 specthread 섹션을
|
|
48
|
+
/** AGENTS.md 의 specthread 섹션을 맞춘다 */
|
|
46
49
|
const ensureAgentsMd = (cwd, scaffold) => {
|
|
47
50
|
const dest = join(cwd, "AGENTS.md");
|
|
48
51
|
const section = readFileSync(join(scaffold, "AGENTS.md"), "utf8");
|
|
49
52
|
if (!existsSync(dest)) {
|
|
50
53
|
writeFileSync(dest, `${wrapSection(section)}\n`, "utf8");
|
|
51
54
|
console.log(" AGENTS.md 생성");
|
|
52
|
-
return
|
|
55
|
+
return "written";
|
|
53
56
|
}
|
|
54
57
|
const content = readFileSync(dest, "utf8");
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
const
|
|
58
|
-
|
|
58
|
+
const start = content.indexOf(SPECTHREAD_START);
|
|
59
|
+
if (start >= 0) {
|
|
60
|
+
const end = content.indexOf(SPECTHREAD_END, start);
|
|
61
|
+
// 끝 표식이 없으면 섹션이 어디서 끝나는지 알 수 없다. 추측해서 바꾸면 사용자 내용을 지운다
|
|
62
|
+
if (end < 0) {
|
|
63
|
+
console.log(` AGENTS.md ${SPECTHREAD_END} 표식 없음. 건드리지 않음`);
|
|
64
|
+
return "broken";
|
|
65
|
+
}
|
|
66
|
+
const after = content.slice(end + SPECTHREAD_END.length);
|
|
67
|
+
writeFileSync(dest, `${content.slice(0, start)}${wrapSection(section)}${after}`, "utf8");
|
|
59
68
|
console.log(" AGENTS.md specthread 섹션 갱신");
|
|
60
|
-
return
|
|
69
|
+
return "written";
|
|
61
70
|
}
|
|
62
71
|
if (isLegacyAgents(content)) {
|
|
63
72
|
console.log(" AGENTS.md 이전 버전 형식 (구분 표식 없음). 건드리지 않음");
|
|
64
|
-
return
|
|
73
|
+
return "legacy";
|
|
65
74
|
}
|
|
66
75
|
writeFileSync(dest, `${content.trimEnd()}\n\n${wrapSection(section)}\n`, "utf8");
|
|
67
76
|
console.log(" AGENTS.md specthread 섹션 삽입");
|
|
68
|
-
return
|
|
77
|
+
return "written";
|
|
69
78
|
};
|
|
70
79
|
const ensureClaudeMd = (cwd) => {
|
|
71
80
|
const dest = join(cwd, "CLAUDE.md");
|
|
@@ -99,6 +108,9 @@ const ensureGitignore = (cwd) => {
|
|
|
99
108
|
console.log(` .gitignore ${LOCAL_CONFIG_PATH} 추가`);
|
|
100
109
|
};
|
|
101
110
|
const SKILLS = ["check", "gen", "plan-open", "plan-run", "plan-close"];
|
|
111
|
+
/** 업데이트 프롬프트 구분선. 사용자가 이 사이를 복사해 AI 에 전달한다 */
|
|
112
|
+
const PROMPT_START = "── 업데이트 프롬프트: 아래를 AI 에게 그대로 전달한다 ──────────────";
|
|
113
|
+
const PROMPT_END = "──────────────────────────────────────────────────────────────";
|
|
102
114
|
const parseTools = (args) => {
|
|
103
115
|
const idx = args.indexOf("--tools");
|
|
104
116
|
if (idx === -1 || idx + 1 >= args.length)
|
|
@@ -108,10 +120,10 @@ const parseTools = (args) => {
|
|
|
108
120
|
const STATUS_LABEL = {
|
|
109
121
|
created: "생성",
|
|
110
122
|
overwritten: "덮어씀",
|
|
123
|
+
unchanged: "변경 없음",
|
|
111
124
|
skipped: "이미 존재. 건너뜀",
|
|
112
125
|
kept: "사용자 파일. 건너뜀",
|
|
113
126
|
};
|
|
114
|
-
const UPGRADE_GUIDE = "README 의 '0.1.x 에서 올리기'";
|
|
115
127
|
export const init = (args) => {
|
|
116
128
|
const cwd = process.cwd();
|
|
117
129
|
const scaffold = scaffoldDir();
|
|
@@ -131,37 +143,42 @@ export const init = (args) => {
|
|
|
131
143
|
}
|
|
132
144
|
const configStatus = putFile(join(cwd, CONFIG_PATH), renderConfig(DEFAULT_CONFIG), force, "user");
|
|
133
145
|
console.log(` ${CONFIG_PATH} ${STATUS_LABEL[configStatus]}`);
|
|
146
|
+
// 내용이 바뀐 패키지 파일. 업데이트 프롬프트가 사용자 수정분 확인을 요청한다
|
|
147
|
+
const overwritten = [];
|
|
148
|
+
const put = ({ src, dest, owner }) => {
|
|
149
|
+
const status = copyFile(src, join(cwd, dest), force, owner);
|
|
150
|
+
if (status === "overwritten")
|
|
151
|
+
overwritten.push(dest);
|
|
152
|
+
console.log(` ${dest} ${STATUS_LABEL[status]}`);
|
|
153
|
+
};
|
|
134
154
|
// scaffold 원본은 고정 경로와 같은 파일 이름을 쓴다
|
|
135
155
|
const docs = [
|
|
136
156
|
[RULES_PATH, "package"],
|
|
137
157
|
[PROJECT_PATH, "user"],
|
|
138
158
|
[PENDING_PATH, "user"],
|
|
139
159
|
];
|
|
140
|
-
for (const [dest, owner] of docs)
|
|
141
|
-
|
|
142
|
-
console.log(` ${dest} ${STATUS_LABEL[status]}`);
|
|
143
|
-
}
|
|
160
|
+
for (const [dest, owner] of docs)
|
|
161
|
+
put({ src: join(scaffold, basename(dest)), dest, owner });
|
|
144
162
|
for (const file of ["spec.md", "plan.md"]) {
|
|
145
|
-
|
|
146
|
-
const status = copyFile(join(scaffold, "templates", file), join(cwd, dest), force, "package");
|
|
147
|
-
console.log(` ${dest} ${STATUS_LABEL[status]}`);
|
|
163
|
+
put({ src: join(scaffold, "templates", file), dest: `${TEMPLATES_DIR}/${file}`, owner: "package" });
|
|
148
164
|
}
|
|
149
|
-
|
|
165
|
+
const agents = ensureAgentsMd(cwd, scaffold);
|
|
150
166
|
ensureGitignore(cwd);
|
|
167
|
+
const oldSkills = [];
|
|
151
168
|
if (tools.has("claude")) {
|
|
152
169
|
ensureClaudeMd(cwd);
|
|
153
|
-
// Claude Code 는 `<이름>/SKILL.md` 만 스킬로 읽는다.
|
|
154
|
-
const skillsDir = join(cwd, ".claude", "skills");
|
|
155
|
-
const oldSkills = [];
|
|
170
|
+
// Claude Code 는 `<이름>/SKILL.md` 만 스킬로 읽는다. `<이름>.md` 는 이전 버전의 경로다
|
|
156
171
|
for (const name of SKILLS) {
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
172
|
+
put({
|
|
173
|
+
src: join(scaffold, "claude", "skills", name, "SKILL.md"),
|
|
174
|
+
dest: `.claude/skills/${name}/SKILL.md`,
|
|
175
|
+
owner: "package",
|
|
176
|
+
});
|
|
177
|
+
if (existsSync(join(cwd, ".claude", "skills", `${name}.md`)))
|
|
160
178
|
oldSkills.push(`.claude/skills/${name}.md`);
|
|
161
179
|
}
|
|
162
180
|
// 사용자가 고쳤을 수 있으므로 지우지 않고 알리기만 한다
|
|
163
181
|
if (oldSkills.length > 0) {
|
|
164
|
-
legacy = true;
|
|
165
182
|
console.log("\n 이전 형식의 스킬 파일이 남아 있다. Claude Code 가 읽지 않으므로 지워도 된다:");
|
|
166
183
|
for (const path of oldSkills)
|
|
167
184
|
console.log(` ${path}`);
|
|
@@ -169,9 +186,16 @@ export const init = (args) => {
|
|
|
169
186
|
}
|
|
170
187
|
if (force) {
|
|
171
188
|
console.log(`\n--force 는 패키지 파일만 갱신한다. ${CONFIG_PATH}, ${PROJECT_PATH}, ${PENDING_PATH} 는 그대로 둔다.`);
|
|
189
|
+
console.log(`\n${PROMPT_START}`);
|
|
190
|
+
console.log(renderUpgradePrompt({ root: cwd, agents, overwritten, oldSkills }));
|
|
191
|
+
console.log(PROMPT_END);
|
|
192
|
+
return;
|
|
193
|
+
}
|
|
194
|
+
if (agents === "broken") {
|
|
195
|
+
console.log(`\nAGENTS.md 의 specthread 섹션 끝에 ${SPECTHREAD_END} 를 넣고 다시 실행한다.`);
|
|
172
196
|
}
|
|
173
|
-
if (legacy) {
|
|
174
|
-
console.log(
|
|
197
|
+
if (agents === "legacy" || oldSkills.length > 0) {
|
|
198
|
+
console.log("\n이전 버전에서 올린 프로젝트로 보인다. `npx specthread init --force` 로 패키지 파일을 갱신하면 남은 정리를 위한 프롬프트를 출력한다.");
|
|
175
199
|
}
|
|
176
200
|
console.log("\n완료. npx specthread check 로 문서 정합성을 확인할 수 있다.");
|
|
177
201
|
};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** AGENTS.md 처리 결과. `legacy`·`broken` 은 파일을 고치지 않은 경우다 */
|
|
2
|
+
export type AgentsStatus = "written" | "legacy" | "broken";
|
|
3
|
+
/** init 이 넘겨주는 상태 */
|
|
4
|
+
export interface UpgradeInput {
|
|
5
|
+
root: string;
|
|
6
|
+
agents: AgentsStatus;
|
|
7
|
+
/** 내용이 바뀐 패키지 파일 */
|
|
8
|
+
overwritten: string[];
|
|
9
|
+
/** `<이름>/SKILL.md` 가 아닌 이전 경로에 남은 스킬 파일 */
|
|
10
|
+
oldSkills: string[];
|
|
11
|
+
}
|
|
12
|
+
export declare const renderUpgradePrompt: (input: UpgradeInput) => string;
|