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.
- package/README.md +139 -0
- package/dist/bin/check.d.ts +1 -0
- package/dist/bin/check.js +67 -0
- package/dist/bin/cli.d.ts +2 -0
- package/dist/bin/cli.js +26 -0
- package/dist/bin/generate.d.ts +1 -0
- package/dist/bin/generate.js +55 -0
- package/dist/checks/changelog.d.ts +8 -0
- package/dist/checks/changelog.js +30 -0
- package/dist/checks/headings.d.ts +3 -0
- package/dist/checks/headings.js +54 -0
- package/dist/checks/links.d.ts +8 -0
- package/dist/checks/links.js +66 -0
- package/dist/checks/markers.d.ts +2 -0
- package/dist/checks/markers.js +60 -0
- package/dist/checks/pending.d.ts +2 -0
- package/dist/checks/pending.js +200 -0
- package/dist/checks/references.d.ts +2 -0
- package/dist/checks/references.js +41 -0
- package/dist/checks/sections.d.ts +3 -0
- package/dist/checks/sections.js +137 -0
- package/dist/checks/style.d.ts +10 -0
- package/dist/checks/style.js +61 -0
- package/dist/checks/timestamps.d.ts +2 -0
- package/dist/checks/timestamps.js +58 -0
- package/dist/checks/toc.d.ts +2 -0
- package/dist/checks/toc.js +41 -0
- package/dist/commands/init.d.ts +1 -0
- package/dist/commands/init.js +115 -0
- package/dist/config-loader.d.ts +2 -0
- package/dist/config-loader.js +106 -0
- package/dist/config.schema.d.ts +96 -0
- package/dist/config.schema.js +27 -0
- package/dist/constants/docs.d.ts +15 -0
- package/dist/constants/docs.js +16 -0
- package/dist/constants/patterns.d.ts +24 -0
- package/dist/constants/patterns.js +24 -0
- package/dist/constants/rules.d.ts +101 -0
- package/dist/constants/rules.js +97 -0
- package/dist/gen/pending-section.d.ts +19 -0
- package/dist/gen/pending-section.js +102 -0
- package/dist/gen/references.d.ts +13 -0
- package/dist/gen/references.js +144 -0
- package/dist/gen/summary.d.ts +27 -0
- package/dist/gen/summary.js +125 -0
- package/dist/gen/toc.d.ts +25 -0
- package/dist/gen/toc.js +66 -0
- package/dist/types.d.ts +125 -0
- package/dist/types.js +1 -0
- package/dist/utils/anchor.d.ts +20 -0
- package/dist/utils/anchor.js +24 -0
- package/dist/utils/ignore.d.ts +11 -0
- package/dist/utils/ignore.js +20 -0
- package/dist/utils/parse.d.ts +50 -0
- package/dist/utils/parse.js +272 -0
- package/dist/utils/report.d.ts +17 -0
- package/dist/utils/report.js +38 -0
- package/dist/utils/resolve.d.ts +21 -0
- package/dist/utils/resolve.js +157 -0
- package/dist/utils/scan.d.ts +11 -0
- package/dist/utils/scan.js +111 -0
- package/dist/utils/scope.d.ts +51 -0
- package/dist/utils/scope.js +55 -0
- package/package.json +29 -0
- package/scaffold/AGENTS.md +67 -0
- package/scaffold/CLAUDE.md +1 -0
- package/scaffold/claude/skills/check.md +43 -0
- package/scaffold/claude/skills/gen.md +41 -0
- package/scaffold/claude/skills/plan-close.md +57 -0
- package/scaffold/claude/skills/plan-open.md +50 -0
- package/scaffold/claude/skills/plan-run.md +51 -0
- package/scaffold/config.jsonc +71 -0
- package/scaffold/pending.md +34 -0
- package/scaffold/project.md +47 -0
- package/scaffold/rules.md +421 -0
- package/scaffold/templates/plan.md +159 -0
- package/scaffold/templates/spec.md +96 -0
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 색인 조립 - 대상 파일을 모아 파싱하고 참조를 해소한다.
|
|
3
|
+
*
|
|
4
|
+
* 검사기와 생성기가 모두 이 색인 하나를 쓴다.
|
|
5
|
+
*/
|
|
6
|
+
import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
|
|
7
|
+
import { join, relative, normalize } from "node:path";
|
|
8
|
+
import { parseIgnoredLines } from "./ignore.js";
|
|
9
|
+
import { parseMarkdown, parseMarkers } from "./parse.js";
|
|
10
|
+
import { makeRefContext, parseSectionRefs } from "./resolve.js";
|
|
11
|
+
/** 프로젝트 루트 절대 경로. 색인 경로를 여기 기준 상대 경로로 통일하는 데 쓴다 */
|
|
12
|
+
export const REPO_ROOT = normalize(process.cwd());
|
|
13
|
+
/** 확장자로 파일 종류를 결정한다 */
|
|
14
|
+
const kindFromPath = (file) => {
|
|
15
|
+
if (/\.md$/i.test(file))
|
|
16
|
+
return "md";
|
|
17
|
+
if (/\.tsx?$/.test(file))
|
|
18
|
+
return "code";
|
|
19
|
+
if (/\.json$/.test(file))
|
|
20
|
+
return "json";
|
|
21
|
+
return null;
|
|
22
|
+
};
|
|
23
|
+
/** 디렉터리를 재귀로 훑어 파일 경로를 모은다. `node_modules` 와 숨김 디렉터리는 건너뛴다 */
|
|
24
|
+
const walk = (dir, out = []) => {
|
|
25
|
+
if (!existsSync(dir))
|
|
26
|
+
return out;
|
|
27
|
+
for (const entry of readdirSync(dir)) {
|
|
28
|
+
if (entry === "node_modules" || entry.startsWith("."))
|
|
29
|
+
continue;
|
|
30
|
+
const full = join(dir, entry);
|
|
31
|
+
if (statSync(full).isDirectory())
|
|
32
|
+
walk(full, out);
|
|
33
|
+
else
|
|
34
|
+
out.push(full);
|
|
35
|
+
}
|
|
36
|
+
return out;
|
|
37
|
+
};
|
|
38
|
+
/**
|
|
39
|
+
* config.path 에서 대상 파일을 모은다.
|
|
40
|
+
*
|
|
41
|
+
* 값이 디렉터리면 재귀 스캔, 파일이면 직접 로드. 파싱 전략은 확장자로 결정한다.
|
|
42
|
+
* 인식하지 못하는 확장자는 건너뛴다.
|
|
43
|
+
*/
|
|
44
|
+
const collectTargets = (pathConfig) => {
|
|
45
|
+
const out = [];
|
|
46
|
+
const seen = new Set();
|
|
47
|
+
const add = (abs) => {
|
|
48
|
+
const rel = relative(REPO_ROOT, abs);
|
|
49
|
+
if (seen.has(rel))
|
|
50
|
+
return;
|
|
51
|
+
const kind = kindFromPath(rel);
|
|
52
|
+
if (kind === null)
|
|
53
|
+
return;
|
|
54
|
+
seen.add(rel);
|
|
55
|
+
out.push({ path: rel, kind });
|
|
56
|
+
};
|
|
57
|
+
for (const paths of Object.values(pathConfig)) {
|
|
58
|
+
for (const entry of paths) {
|
|
59
|
+
const abs = join(REPO_ROOT, entry);
|
|
60
|
+
if (!existsSync(abs))
|
|
61
|
+
continue;
|
|
62
|
+
if (statSync(abs).isDirectory()) {
|
|
63
|
+
for (const file of walk(abs))
|
|
64
|
+
add(file);
|
|
65
|
+
}
|
|
66
|
+
else {
|
|
67
|
+
add(abs);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return out;
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* 색인을 만든다. 검사기와 생성기의 유일한 입력이다.
|
|
75
|
+
*
|
|
76
|
+
* 참조 해소 문맥을 먼저 만들어야 하므로 문서 목록을 두 번 본다 - 한 번은 이름 색인을
|
|
77
|
+
* 위해, 한 번은 실제 파싱을 위해. 코드와 JSON 은 헤딩이 없어서 빈 값으로 채운다.
|
|
78
|
+
*/
|
|
79
|
+
export const buildIndex = (config) => {
|
|
80
|
+
const targets = collectTargets(config.path);
|
|
81
|
+
const mdPaths = targets.filter((t) => t.kind === "md").map((t) => t.path);
|
|
82
|
+
const ctx = makeRefContext(mdPaths, config.ignoreDocNames);
|
|
83
|
+
const files = new Map();
|
|
84
|
+
for (const { path, kind } of targets) {
|
|
85
|
+
const lines = readFileSync(join(REPO_ROOT, path), "utf8").split("\n");
|
|
86
|
+
const sectionRefs = parseSectionRefs(path, kind, lines, ctx);
|
|
87
|
+
const ignored = parseIgnoredLines(lines);
|
|
88
|
+
if (kind === "md") {
|
|
89
|
+
files.set(path, { ...parseMarkdown(path, lines), sectionRefs, ignored });
|
|
90
|
+
}
|
|
91
|
+
else {
|
|
92
|
+
files.set(path, {
|
|
93
|
+
path,
|
|
94
|
+
kind,
|
|
95
|
+
lines,
|
|
96
|
+
headings: [],
|
|
97
|
+
links: [],
|
|
98
|
+
sectionRefs,
|
|
99
|
+
markers: parseMarkers(lines, kind),
|
|
100
|
+
pendingItems: [],
|
|
101
|
+
tocBlock: null,
|
|
102
|
+
refSection: null,
|
|
103
|
+
pendingSection: null,
|
|
104
|
+
changeLogRange: null,
|
|
105
|
+
changeLogDates: [],
|
|
106
|
+
ignored,
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return { files, docsByName: ctx.nameMap, config };
|
|
111
|
+
};
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 대상 판정 - 무엇을 검사·생성 대상으로 볼지.
|
|
3
|
+
*
|
|
4
|
+
* 변경 이력 절은 과거 상태를 적은 곳이다. 지워진 문서를 가리키는 것이 정상이므로
|
|
5
|
+
* 링크·절 참조 검사에서 뺀다. 지키게 하면 이력을 고쳐 써야 하는데, 그건
|
|
6
|
+
* [`docs/system/rules.md`](../../docs/system/rules.md) §2-1 이 이력에 사건 기록을
|
|
7
|
+
* 남기라고 한 것과 어긋난다. 참조 절과 미확정 사항 절은 현재 상태라 검사한다.
|
|
8
|
+
*/
|
|
9
|
+
import type { SpecthreadConfig } from "../config.schema.ts";
|
|
10
|
+
import type { Finding, Heading, IndexedFile } from "../types.ts";
|
|
11
|
+
/** 변경 이력 절 안의 줄인지 */
|
|
12
|
+
export declare const inChangeLog: (file: IndexedFile, line: number) => boolean;
|
|
13
|
+
/** 규칙을 적용할 파일인지. skipCheck 의 string 항목(경로 접두사)에 걸리면 제외 */
|
|
14
|
+
export declare const isCheckTarget: (path: string, config: SpecthreadConfig) => boolean;
|
|
15
|
+
/**
|
|
16
|
+
* 목차 블록 안의 줄인지.
|
|
17
|
+
*
|
|
18
|
+
* 목차는 헤딩을 복사해 기계가 만든다. 제목에 `§` 가 들어 있으면 목차에도 실려
|
|
19
|
+
* 같은 지적이 두 번 나온다. 생성물은 원본만 검사한다.
|
|
20
|
+
*/
|
|
21
|
+
export declare const inToc: (file: IndexedFile, line: number) => boolean;
|
|
22
|
+
/**
|
|
23
|
+
* 참조 절 안의 줄인지.
|
|
24
|
+
*
|
|
25
|
+
* 참조 절의 줄 끝 `§N` 은 **이 문서의 어느 절에서 가리켰는지** 를 적은 역링크라,
|
|
26
|
+
* 같은 줄 왼쪽 문서명을 대상으로 삼는 해소 규칙과 방향이 반대다. 그대로 두면
|
|
27
|
+
* 기계 생성물이 스스로 깨진 참조로 잡힌다.
|
|
28
|
+
*/
|
|
29
|
+
export declare const inRefSection: (file: IndexedFile, line: number) => boolean;
|
|
30
|
+
/**
|
|
31
|
+
* 헤딩 줄인지.
|
|
32
|
+
*
|
|
33
|
+
* 제목 안 `§` 는 이름의 일부이지 참조가 아니다. 제목에 마일스톤 라벨을 넣은 것은
|
|
34
|
+
* 규칙 1 위반이라 그 규칙을 보는 검사가 따로 잡아야 한다.
|
|
35
|
+
*/
|
|
36
|
+
export declare const isHeadingLine: (file: IndexedFile, line: number) => boolean;
|
|
37
|
+
/** 규칙을 적용할 마크다운 문서인지. 검사기와 생성기가 같은 기준으로 걸러야 한다 */
|
|
38
|
+
export declare const isTargetDoc: (file: IndexedFile, config: SpecthreadConfig) => boolean;
|
|
39
|
+
/** 참조 절을 생성·검사할 문서인지. skipRefs 에 등록된 경로는 제외한다 */
|
|
40
|
+
export declare const wantsRefSection: (file: IndexedFile, config: SpecthreadConfig) => boolean;
|
|
41
|
+
/** 문서 제목 헤딩 목록. 하나여야 정상이다 */
|
|
42
|
+
export declare const titleHeadings: (file: IndexedFile) => Heading[];
|
|
43
|
+
/** 문서 제목의 헤딩. 하나가 아니면 null */
|
|
44
|
+
export declare const singleTitle: (file: IndexedFile) => Heading | null;
|
|
45
|
+
/**
|
|
46
|
+
* skipCheck 의 객체 항목에 걸리는 지적인지.
|
|
47
|
+
*
|
|
48
|
+
* `{ path, only }` 는 해당 경로에서 `only` 에 나열된 규칙군만 유지한다는 뜻이다.
|
|
49
|
+
* 그 밖의 규칙군에 속하는 지적은 여기서 걸러진다.
|
|
50
|
+
*/
|
|
51
|
+
export declare const isWorkExempt: (finding: Finding, config: SpecthreadConfig) => boolean;
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/** 변경 이력 절 안의 줄인지 */
|
|
2
|
+
export const inChangeLog = (file, line) => file.changeLogRange !== null &&
|
|
3
|
+
line >= file.changeLogRange.start &&
|
|
4
|
+
line <= file.changeLogRange.end;
|
|
5
|
+
/** 규칙을 적용할 파일인지. skipCheck 의 string 항목(경로 접두사)에 걸리면 제외 */
|
|
6
|
+
export const isCheckTarget = (path, config) => !config.skipCheck.some((entry) => typeof entry === "string" && path.startsWith(entry));
|
|
7
|
+
/**
|
|
8
|
+
* 목차 블록 안의 줄인지.
|
|
9
|
+
*
|
|
10
|
+
* 목차는 헤딩을 복사해 기계가 만든다. 제목에 `§` 가 들어 있으면 목차에도 실려
|
|
11
|
+
* 같은 지적이 두 번 나온다. 생성물은 원본만 검사한다.
|
|
12
|
+
*/
|
|
13
|
+
export const inToc = (file, line) => file.tocBlock !== null && line >= file.tocBlock.start && line <= file.tocBlock.end;
|
|
14
|
+
/**
|
|
15
|
+
* 참조 절 안의 줄인지.
|
|
16
|
+
*
|
|
17
|
+
* 참조 절의 줄 끝 `§N` 은 **이 문서의 어느 절에서 가리켰는지** 를 적은 역링크라,
|
|
18
|
+
* 같은 줄 왼쪽 문서명을 대상으로 삼는 해소 규칙과 방향이 반대다. 그대로 두면
|
|
19
|
+
* 기계 생성물이 스스로 깨진 참조로 잡힌다.
|
|
20
|
+
*/
|
|
21
|
+
export const inRefSection = (file, line) => file.refSection !== null &&
|
|
22
|
+
line >= file.refSection.start &&
|
|
23
|
+
line <= file.refSection.end;
|
|
24
|
+
/**
|
|
25
|
+
* 헤딩 줄인지.
|
|
26
|
+
*
|
|
27
|
+
* 제목 안 `§` 는 이름의 일부이지 참조가 아니다. 제목에 마일스톤 라벨을 넣은 것은
|
|
28
|
+
* 규칙 1 위반이라 그 규칙을 보는 검사가 따로 잡아야 한다.
|
|
29
|
+
*/
|
|
30
|
+
export const isHeadingLine = (file, line) => file.headings.some((h) => h.line === line);
|
|
31
|
+
/** 규칙을 적용할 마크다운 문서인지. 검사기와 생성기가 같은 기준으로 걸러야 한다 */
|
|
32
|
+
export const isTargetDoc = (file, config) => file.kind === 'md' && isCheckTarget(file.path, config);
|
|
33
|
+
/** 참조 절을 생성·검사할 문서인지. skipRefs 에 등록된 경로는 제외한다 */
|
|
34
|
+
export const wantsRefSection = (file, config) => isTargetDoc(file, config) && !config.skipRefs.includes(file.path);
|
|
35
|
+
/** 문서 제목 헤딩 목록. 하나여야 정상이다 */
|
|
36
|
+
export const titleHeadings = (file) => file.headings.filter((h) => h.level === 1);
|
|
37
|
+
/** 문서 제목의 헤딩. 하나가 아니면 null */
|
|
38
|
+
export const singleTitle = (file) => {
|
|
39
|
+
const titles = titleHeadings(file);
|
|
40
|
+
return titles.length === 1 ? titles[0] : null;
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* skipCheck 의 객체 항목에 걸리는 지적인지.
|
|
44
|
+
*
|
|
45
|
+
* `{ path, only }` 는 해당 경로에서 `only` 에 나열된 규칙군만 유지한다는 뜻이다.
|
|
46
|
+
* 그 밖의 규칙군에 속하는 지적은 여기서 걸러진다.
|
|
47
|
+
*/
|
|
48
|
+
export const isWorkExempt = (finding, config) => config.skipCheck.some((entry) => {
|
|
49
|
+
if (typeof entry === "string")
|
|
50
|
+
return false;
|
|
51
|
+
if (!finding.file.startsWith(entry.path))
|
|
52
|
+
return false;
|
|
53
|
+
const group = finding.rule.split("/")[0];
|
|
54
|
+
return !entry.only.some((g) => g === group);
|
|
55
|
+
});
|
package/package.json
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "specthread",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Spec-Driven Development (SDD) template. Docs are the single source of truth; code implements docs.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"specthread": "./dist/bin/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"dist/",
|
|
11
|
+
"scaffold/"
|
|
12
|
+
],
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=18.0.0"
|
|
16
|
+
},
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "tsc -p tsconfig.build.json",
|
|
19
|
+
"prepublishOnly": "npm run build",
|
|
20
|
+
"docs:check": "node tools/docs/bin/check.ts",
|
|
21
|
+
"docs:generate": "node tools/docs/bin/generate.ts",
|
|
22
|
+
"docs:test": "node --test \"tools/docs/__tests__/*.test.ts\"",
|
|
23
|
+
"docs:typecheck": "tsc -p tools/tsconfig.json"
|
|
24
|
+
},
|
|
25
|
+
"devDependencies": {
|
|
26
|
+
"@types/node": "^26.5.1",
|
|
27
|
+
"typescript": "^7.0.2"
|
|
28
|
+
}
|
|
29
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# specthread
|
|
2
|
+
|
|
3
|
+
**목차**
|
|
4
|
+
|
|
5
|
+
- [1. 개요](#1-개요)
|
|
6
|
+
- [2. SDD 작업 흐름](#2-sdd-작업-흐름)
|
|
7
|
+
- [3. 문서 체계](#3-문서-체계)
|
|
8
|
+
- [4. 미확정 마커](#4-미확정-마커)
|
|
9
|
+
- [5. 문서 작성 컨벤션](#5-문서-작성-컨벤션)
|
|
10
|
+
|
|
11
|
+
## 1. 개요
|
|
12
|
+
|
|
13
|
+
Spec-Driven Development (SDD) 템플릿. 문서가 단일 진실 원천이고 코드는 문서를 구현한다. 설정(`config.jsonc`)과 도구(`check`/`gen`)로 문서 체계를 지원한다.
|
|
14
|
+
|
|
15
|
+
- **spec 이 정본이다.** 코드와 충돌하면 spec 우선. 코드 변경이 시스템 동작을 바꾸면 spec 동시 갱신 의무.
|
|
16
|
+
- **설정**: `config.jsonc` (프로젝트 공유) + `config.local.jsonc` (개인, gitignore 대상).
|
|
17
|
+
- **도구**: `npx specthread check` 는 규칙 위반을 검사하고, `npx specthread gen` 은 참조 절·미확정 사항 뷰를 생성한다.
|
|
18
|
+
|
|
19
|
+
## 2. SDD 작업 흐름
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
1. 스펙 확인 → 2. 현황 점검(check) → 3. 계획 수립 → 4. 구현 → 5. 검증(check) → 6. 문서 갱신
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- 구현 전에 spec 을 읽고, 구현 후에 spec 을 갱신한다.
|
|
26
|
+
- 진행 중 모호함을 발견하면 `PENDING` 마커를 남기고 작업을 계속한다 (§4).
|
|
27
|
+
|
|
28
|
+
## 3. 문서 체계
|
|
29
|
+
|
|
30
|
+
아래는 기본 경로다. `config.jsonc` 에서 override 했으면 그쪽이 우선한다.
|
|
31
|
+
|
|
32
|
+
| 기본 경로 | 역할 |
|
|
33
|
+
| ------------------------ | ---------------------------------- |
|
|
34
|
+
| `specthread/rules.md` | 문서 형식 규칙 (코어) |
|
|
35
|
+
| `specthread/project.md` | 설정값의 맥락과 프로젝트 고유 설명 |
|
|
36
|
+
| `specthread/pending.md` | 미확정 사항 정본 |
|
|
37
|
+
|
|
38
|
+
문서 유형 정의 (어떤 경로가 어떤 템플릿을 쓰는지) 는 `config.docTypes` 가 정본이다.
|
|
39
|
+
|
|
40
|
+
`docs/` 안 문서를 편집할 때는 `rules.md` 를 먼저 읽는다.
|
|
41
|
+
|
|
42
|
+
## 4. 미확정 마커
|
|
43
|
+
|
|
44
|
+
미완·임시 코드·데이터·디자인은 `PENDING::<종류>::<slug>` 마커로 명시한다. slug 가 `specthread/pending.md` 항목 하나를 가리킨다.
|
|
45
|
+
|
|
46
|
+
위치별 표기:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
코드 / CSS // PENDING::design::slug
|
|
50
|
+
JSON 데이터 "_pending": "design::slug"
|
|
51
|
+
Markdown 문서 본문에 `PENDING::design::slug` 인용
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- 형식·검사 규칙: `rules.md` §4
|
|
55
|
+
- 종류 값: `config.markers.types` (`system` 은 코어 예약)
|
|
56
|
+
- 시점 라벨: `config.markers.timepoints`
|
|
57
|
+
- 종류별 맥락·처리자: `project.md` §2
|
|
58
|
+
|
|
59
|
+
## 5. 문서 작성 컨벤션
|
|
60
|
+
|
|
61
|
+
`docs/` 안 문서에 적용되는 핵심 규칙. 전체 규칙은 `rules.md`.
|
|
62
|
+
|
|
63
|
+
- **목차**: `## 1.` 이상 모든 번호 헤딩을 나열한다. 꼬리 절 (참조, 미확정 사항, 변경 이력) 은 무번호.
|
|
64
|
+
- **변경 이력**: 문서 하단에 `| 날짜 | 내용 |` 표. 한 커밋이 한 줄.
|
|
65
|
+
- **참조 절**: 도구가 본문 링크를 모아 생성한다. 사람이 쓰지 않는다.
|
|
66
|
+
- **빈 섹션**: `해당 없음 - <이유>`. 제목만 두지 않는다.
|
|
67
|
+
- **시점·버전 정보**: 본문이 아니라 변경 이력에 남긴다.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 문서 정합성 검사를 실행하고 결과를 해석한다
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# check
|
|
6
|
+
|
|
7
|
+
문서 규칙 위반을 검사하고, 결과를 해석해서 해결 방법을 안내한다.
|
|
8
|
+
|
|
9
|
+
## 실행
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx specthread check
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 결과 해석
|
|
16
|
+
|
|
17
|
+
출력은 두 부분으로 나뉜다:
|
|
18
|
+
|
|
19
|
+
1. **색인 요약** - 검사 대상 규모 (문서/코드/데이터 수, 헤딩/링크/마커 수, 인라인 억제 수)
|
|
20
|
+
2. **지적 목록** - 파일별 줄 번호 + 규칙 ID + 메시지
|
|
21
|
+
|
|
22
|
+
## 규칙 ID별 해결 방법
|
|
23
|
+
|
|
24
|
+
| 규칙 ID | 의미 | 해결 |
|
|
25
|
+
|---------|------|------|
|
|
26
|
+
| `toc/stale` | 목차가 헤딩과 어긋남 | `npx specthread gen --write` |
|
|
27
|
+
| `reference/stale` | 참조 절이 본문 링크와 어긋남 | `npx specthread gen --write` |
|
|
28
|
+
| `pending/section-stale` | 미확정 사항 절이 관리 문서와 어긋남 | `npx specthread gen --write` |
|
|
29
|
+
| `heading/tail-name-reused` | 본문 절 제목이 꼬리 절 이름과 같음 | 절 제목 변경 |
|
|
30
|
+
| `section-ref/not-linked` | 다른 문서 절 참조에 앵커 링크가 없음 | 앵커 링크로 변환 |
|
|
31
|
+
| `marker/orphan` | 마커를 가리키는 관리 문서 항목 없음 | `specthread/pending.md`에 항목 추가 |
|
|
32
|
+
| `changelog/order` | 변경 이력 날짜 순서 어긋남 | 날짜 순 정렬 |
|
|
33
|
+
| `style/em-dash` | em dash 사용 | 하이픈으로 교체 |
|
|
34
|
+
|
|
35
|
+
## 행동 지침
|
|
36
|
+
|
|
37
|
+
1. 검사를 실행한다.
|
|
38
|
+
2. 지적이 0건이면 "문서 정합성 검사 통과"로 끝낸다.
|
|
39
|
+
3. 지적이 있으면:
|
|
40
|
+
- `toc/stale`, `reference/stale`, `pending/section-stale`은 `npx specthread gen --write`로 한번에 해결할 수 있다고 안내한다.
|
|
41
|
+
- 나머지는 규칙 ID별 해결 방법을 파일·줄 번호와 함께 안내한다.
|
|
42
|
+
- 사용자가 수정을 요청하면 해당 파일을 직접 수정한다.
|
|
43
|
+
4. 수정 후 다시 검사를 실행해서 해결을 확인한다.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 참조 절·목차·요약 표를 생성하고 결과를 안내한다
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# gen
|
|
6
|
+
|
|
7
|
+
본문 링크와 헤딩을 기반으로 참조 절·목차·미확정 사항 요약 표를 생성한다.
|
|
8
|
+
|
|
9
|
+
## 실행
|
|
10
|
+
|
|
11
|
+
미리보기 (변경 대상만 확인):
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx specthread gen
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
실제 적용:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx specthread gen --write
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 생성 항목
|
|
24
|
+
|
|
25
|
+
| 항목 | 동작 | 조건 |
|
|
26
|
+
|------|------|------|
|
|
27
|
+
| 참조 절 | 본문 링크를 모아 `## 참조` 절을 채움 | `features.references: true` |
|
|
28
|
+
| 목차 | 번호 헤딩을 모아 목차 블록을 갱신 | 항상 |
|
|
29
|
+
| 미확정 사항 절 | `specthread/pending.md` 항목을 문서별 `## 미확정 사항` 절에 반영 | `features.markers: true` |
|
|
30
|
+
| 요약 표 | 미확정 사항 절 머리에 종류·시점·마커 수 표를 채움 | `features.markers: true` |
|
|
31
|
+
|
|
32
|
+
## 행동 지침
|
|
33
|
+
|
|
34
|
+
1. 먼저 미리보기(`npx specthread gen`)를 실행한다.
|
|
35
|
+
2. 변경 대상 파일 목록을 사용자에게 보여준다.
|
|
36
|
+
3. 변경이 0건이면 "생성할 변경 사항 없음"으로 끝낸다.
|
|
37
|
+
4. 변경이 있으면:
|
|
38
|
+
- 어떤 파일의 어떤 절이 갱신되는지 요약한다.
|
|
39
|
+
- 사용자에게 적용 여부를 확인한다.
|
|
40
|
+
- 승인하면 `npx specthread gen --write`를 실행한다.
|
|
41
|
+
5. 적용 후 `npx specthread check`를 실행해서 생성 관련 지적(`toc/stale`, `reference/stale`, `pending/section-stale`)이 해소되었는지 확인한다.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 완료된 작업의 내용을 spec에 반영하고 work 문서를 삭제한다
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# plan-close
|
|
6
|
+
|
|
7
|
+
작업이 완료된 plan 문서의 내용을 spec 본문에 흡수하고, work 문서를 삭제하여 하나의 작업을 종료하는 흐름.
|
|
8
|
+
|
|
9
|
+
## 인자
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
/plan-close ← 컨텍스트에서 plan 문서 탐색
|
|
13
|
+
/plan-close docs/work/auth-flow.md ← 명시 지정
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
인자가 없으면 `docs/work/` 안에서 모든 단계가 완료된 문서를 찾는다.
|
|
17
|
+
|
|
18
|
+
## 흐름
|
|
19
|
+
|
|
20
|
+
### 1. 종료 조건 확인
|
|
21
|
+
|
|
22
|
+
1. plan 문서의 **작업 단계** 표에서 모든 행이 `완료` 또는 `건너뜀`인지 확인한다.
|
|
23
|
+
2. **종료 게이트**의 조건을 하나씩 점검한다.
|
|
24
|
+
3. 미충족 조건이 있으면 사용자에게 알리고, `/plan-run`으로 돌아갈지 그대로 닫을지 확인한다.
|
|
25
|
+
|
|
26
|
+
### 2. spec 반영
|
|
27
|
+
|
|
28
|
+
plan 문서의 내용을 spec 문서에 흡수한다.
|
|
29
|
+
|
|
30
|
+
**대상 spec 판단:**
|
|
31
|
+
1. plan 문서의 **참조 절**에 링크된 spec 문서가 있으면 해당 spec에 머지한다.
|
|
32
|
+
2. 기존 spec의 **"다루는 범위 / 다루지 않는 범위"** 표를 확인하여, 이 작업 내용이 기존 spec의 범위에 속하는지 판단한다.
|
|
33
|
+
3. 어느 spec에도 속하지 않는 새 도메인이면 새 spec을 생성한다.
|
|
34
|
+
4. 여러 spec에 걸치면 각각에 해당 부분을 나누어 반영한다.
|
|
35
|
+
|
|
36
|
+
**반영 내용:**
|
|
37
|
+
- 작업 범위 상세의 설계 결정 → spec 본문 해당 절
|
|
38
|
+
- 다루지 않는 항목 중 이관 처리된 것 → 대상 spec의 범위 표
|
|
39
|
+
- 새로 생긴 PENDING 마커 → `specthread/pending.md` 항목 확인
|
|
40
|
+
|
|
41
|
+
### 3. 정합성 검사
|
|
42
|
+
|
|
43
|
+
1. `npx specthread gen --write`로 참조 절·목차·미확정 사항 절을 갱신한다.
|
|
44
|
+
2. `npx specthread check`로 전체 정합성을 확인한다.
|
|
45
|
+
3. 지적이 있으면 수정한다.
|
|
46
|
+
|
|
47
|
+
### 4. work 문서 삭제
|
|
48
|
+
|
|
49
|
+
1. 사용자에게 삭제 대상 파일을 보여주고 확인을 받는다.
|
|
50
|
+
2. 승인하면 `docs/work/<name>.md`를 삭제한다.
|
|
51
|
+
3. 삭제 후 `npx specthread check`를 한 번 더 실행하여 깨진 링크가 없는지 확인한다.
|
|
52
|
+
|
|
53
|
+
## 판단 기준
|
|
54
|
+
|
|
55
|
+
- spec 반영 전에 반드시 사용자 확인을 받는다. 자동으로 머지하지 않는다.
|
|
56
|
+
- 새 spec 생성 시 사용자에게 파일 이름과 위치를 확인한다.
|
|
57
|
+
- work 문서 삭제는 항상 사용자 승인 후에만 실행한다.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 작업 계획 문서를 작성하고 검수를 거쳐 확정한다
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# plan-open
|
|
6
|
+
|
|
7
|
+
새 작업의 계획 문서를 `docs/work/`에 생성하고, 검수를 거쳐 확정하는 흐름.
|
|
8
|
+
|
|
9
|
+
## 인자
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
/plan-open ← 새 작업 문서 생성
|
|
13
|
+
/plan-open docs/work/auth-flow.md ← 기존 초안 이어서 작업
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
인자가 없으면 작업 이름을 물어본 뒤 `docs/work/<name>.md`를 새로 만든다.
|
|
17
|
+
인자가 있으면 해당 파일을 읽고 이어서 진행한다.
|
|
18
|
+
|
|
19
|
+
## 흐름
|
|
20
|
+
|
|
21
|
+
### 1. 초안 작성
|
|
22
|
+
|
|
23
|
+
1. 사용자와 대화하며 각 절을 채운다:
|
|
24
|
+
- **목표 + 종료 게이트**: 검증 가능한 조건으로. "잘 정리됐다"는 게이트가 아니다.
|
|
25
|
+
- **작업 단계**: 순서와 의존 관계.
|
|
26
|
+
- **작업 범위 상세**: 코드 시그니처, 데이터 모양, 예시 등 구체적 내용.
|
|
27
|
+
- **영향 파일**: 실제로 손댈 파일. 이 절을 못 채우면 계획이 덜 선 것이다.
|
|
28
|
+
- **다루지 않는 항목**: 후보에서 빠진 것을 처리·이유와 함께 적는다.
|
|
29
|
+
- **검증 기준**: 자동(테스트, 빌드)과 사용자(기능 동작, 시각 검수)를 나눈다.
|
|
30
|
+
- **예상 산출물**: 코드 외에 갱신할 문서가 있으면 함께 적는다.
|
|
31
|
+
2. 모호한 부분은 `PENDING::<종류>::<slug>` 마커를 남기고 넘어간다.
|
|
32
|
+
3. 결정 사항은 별도 절이 아니라 **해당 절 본문에** 반영하고, 변경 이력에 기록한다.
|
|
33
|
+
|
|
34
|
+
### 2. 검수
|
|
35
|
+
|
|
36
|
+
1. 초안을 사용자에게 제시한다.
|
|
37
|
+
2. `npx specthread check`를 실행해서 형식 문제를 확인한다.
|
|
38
|
+
3. 사용자 피드백을 반영하여 수정한다.
|
|
39
|
+
|
|
40
|
+
### 3. 확정
|
|
41
|
+
|
|
42
|
+
1. 사용자가 승인하면 `npx specthread gen --write`로 참조 절·목차를 채운다.
|
|
43
|
+
2. 최종 `npx specthread check`로 정합성을 확인한다.
|
|
44
|
+
3. 문서가 확정되었음을 안내하고, 다음 단계(`/plan-run`)를 안내한다.
|
|
45
|
+
|
|
46
|
+
## 판단 기준
|
|
47
|
+
|
|
48
|
+
- 영향 파일 절이 비어 있으면 확정하지 않는다.
|
|
49
|
+
- 종료 게이트가 검증 불가능하면 다시 쓴다.
|
|
50
|
+
- 미확정 마커는 있어도 확정 가능하다 - 작업을 멈추지 않기 위한 장치다.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 확정된 계획 문서에 따라 작업을 실행하고 미결 사항을 기록한다
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# plan-run
|
|
6
|
+
|
|
7
|
+
확정된 계획 문서의 작업 단계를 실행하고, 미결 사항을 기록하며, 검토를 거쳐 보완하는 흐름.
|
|
8
|
+
|
|
9
|
+
## 인자
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
/plan-run ← 컨텍스트에서 plan 문서 탐색
|
|
13
|
+
/plan-run docs/work/auth-flow.md ← 명시 지정
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
인자가 없으면 `docs/work/` 안에서 현재 작업과 관련된 문서를 찾는다.
|
|
17
|
+
|
|
18
|
+
## 흐름
|
|
19
|
+
|
|
20
|
+
### 1. 작업 파악
|
|
21
|
+
|
|
22
|
+
1. plan 문서의 **작업 단계** 표를 읽는다.
|
|
23
|
+
2. 상태가 `대기`인 첫 번째 단계를 확인한다.
|
|
24
|
+
3. 해당 단계의 **작업 범위 상세** 절을 읽고 무엇을 할지 파악한다.
|
|
25
|
+
|
|
26
|
+
### 2. 실행
|
|
27
|
+
|
|
28
|
+
1. 작업 범위 상세에 따라 구현한다.
|
|
29
|
+
2. 진행 중 모호함을 발견하면:
|
|
30
|
+
- 코드/문서에 `PENDING::<종류>::<slug>` 마커를 남긴다.
|
|
31
|
+
- `specthread/pending.md`에 항목을 추가한다 (`rules.md` §4-2 형식).
|
|
32
|
+
3. 단계가 끝나면 plan 문서의 작업 단계 표에서 해당 행의 상태를 `완료`로 갱신한다.
|
|
33
|
+
|
|
34
|
+
### 3. 검토
|
|
35
|
+
|
|
36
|
+
1. `npx specthread check`를 실행한다.
|
|
37
|
+
2. 검증 기준(자동 + 사용자)을 확인한다.
|
|
38
|
+
3. 사용자에게 검토 결과를 제시한다.
|
|
39
|
+
|
|
40
|
+
### 4. 보완
|
|
41
|
+
|
|
42
|
+
1. 사용자 피드백에 따라 수정한다.
|
|
43
|
+
2. plan 문서의 변경 이력에 기록한다.
|
|
44
|
+
3. 다음 단계가 있으면 1번으로 돌아간다.
|
|
45
|
+
4. 모든 단계가 완료되면 `/plan-close`를 안내한다.
|
|
46
|
+
|
|
47
|
+
## 판단 기준
|
|
48
|
+
|
|
49
|
+
- plan 문서의 작업 단계 표가 유일한 진행 상태 원천이다. 별도 상태 표기를 만들지 않는다.
|
|
50
|
+
- 결정 사항은 plan 문서 해당 절 본문에 반영하고, 변경 이력에 남긴다.
|
|
51
|
+
- 예상 산출물에 적힌 문서 갱신을 빠뜨리지 않는다.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
{
|
|
2
|
+
// ── specthread 설정 ──────────────────────────────────────────────
|
|
3
|
+
// 생략한 키는 기본값이 적용된다. 개인 설정은 config.local.jsonc (gitignore 대상).
|
|
4
|
+
|
|
5
|
+
// ── 스캔 대상 경로 ───────────────────────────────────────────────
|
|
6
|
+
// 자유 KV. 키는 용도 라벨, 값은 경로 배열.
|
|
7
|
+
// 디렉터리면 재귀 스캔, 파일이면 직접 로드.
|
|
8
|
+
// 예: "source": ["client/src/"], "data": ["data/"]
|
|
9
|
+
// "meta": ["CLAUDE.md", "AGENTS.md"]
|
|
10
|
+
"path": {
|
|
11
|
+
"docs": ["docs/"],
|
|
12
|
+
"specthread": ["specthread/"]
|
|
13
|
+
},
|
|
14
|
+
|
|
15
|
+
// ── 기능 플래그 ──────────────────────────────────────────────────
|
|
16
|
+
// 기능 단위 on/off. 개별 규칙이 아닌 기능 묶음으로 제어한다.
|
|
17
|
+
"features": {
|
|
18
|
+
// 마커 체계 전체. false → marker/*, pending/* 검사 + pending 추적 비활성화
|
|
19
|
+
"markers": true,
|
|
20
|
+
// em dash 검사 + 치환 훅. false → style/em-dash 검사 + hook 비활성화
|
|
21
|
+
"emDash": true,
|
|
22
|
+
// 참조 절 자동 생성. false → reference/* 검사 + gen references 스킵
|
|
23
|
+
"references": true
|
|
24
|
+
},
|
|
25
|
+
|
|
26
|
+
// ── 마커 체계 ────────────────────────────────────────────────────
|
|
27
|
+
"markers": {
|
|
28
|
+
// 마커 종류. "system" 은 코어 예약, 나머지는 프로젝트 정의.
|
|
29
|
+
// 예: ["system", "design", "balance", "deps"]
|
|
30
|
+
"types": ["system"],
|
|
31
|
+
// 처리 시점 라벨. 마일스톤 등.
|
|
32
|
+
// 예: ["M1", "M2", "M3"]
|
|
33
|
+
"timepoints": []
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// ── 문서 유형 (기본값: {}) ───────────────────────────────────────
|
|
37
|
+
// 경로 패턴별 템플릿과 프론트매터 스키마를 지정한다.
|
|
38
|
+
// "docTypes": {
|
|
39
|
+
// "spec": {
|
|
40
|
+
// "path": "docs/spec/",
|
|
41
|
+
// "template": "docs/templates/spec.md",
|
|
42
|
+
// "frontmatter": { "required": ["title"], "optional": ["status"] }
|
|
43
|
+
// }
|
|
44
|
+
// }
|
|
45
|
+
|
|
46
|
+
// ── 문서명 해소 무시 (기본값: []) ────────────────────────────────
|
|
47
|
+
// 절 참조(예: "spec §4")가 파일명과 잘못 매칭되는 것을 방지한다.
|
|
48
|
+
// "ignoreDocNames": ["spec"]
|
|
49
|
+
|
|
50
|
+
// ── 검사 제외 (기본값: []) ───────────────────────────────────────
|
|
51
|
+
// 경로 prefix 로 전체 검사를 건너뛰거나, 특정 군만 검사한다.
|
|
52
|
+
// "skipCheck": [
|
|
53
|
+
// "docs/archive/",
|
|
54
|
+
// { "path": "docs/drafts/", "only": ["heading", "link"] }
|
|
55
|
+
// ]
|
|
56
|
+
|
|
57
|
+
// ── 참조 절 생성 제외 (기본값: []) ──────────────────────────────
|
|
58
|
+
// 이 경로 prefix 의 문서에는 참조 절을 생성하지 않는다.
|
|
59
|
+
// "skipRefs": ["docs/templates/"]
|
|
60
|
+
|
|
61
|
+
// ── 로케일 (기본값: "ko") ───────────────────────────────────────
|
|
62
|
+
// 현재 한국어 고정. 검사 메시지, 꼬리 절 이름, 시점 정규식 등에 영향.
|
|
63
|
+
// "locale": "ko"
|
|
64
|
+
|
|
65
|
+
// ── 규약 경로 ────────────────────────────────────────────────────
|
|
66
|
+
// 도구가 직접 읽고 쓰는 파일. path 와 별개.
|
|
67
|
+
// "rules": "specthread/rules.md",
|
|
68
|
+
// "pending": "specthread/pending.md",
|
|
69
|
+
// "project": "specthread/project.md",
|
|
70
|
+
// "work": "docs/work/"
|
|
71
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# pending
|
|
2
|
+
|
|
3
|
+
**목차**
|
|
4
|
+
|
|
5
|
+
- [1. 개요](#1-개요)
|
|
6
|
+
- [참조](#참조)
|
|
7
|
+
- [변경 이력](#변경-이력)
|
|
8
|
+
|
|
9
|
+
## 1. 개요
|
|
10
|
+
|
|
11
|
+
미확정 사항을 기록하고 추적하는 정본 문서. 진행 중 발견한 모호함 때문에 작업을 멈추지 않기 위한 장치다.
|
|
12
|
+
|
|
13
|
+
**설명은 이 문서에만 쓴다.** 발생 지점에는 `PENDING::<종류>::<slug>` 마커만 두고, 각 문서 하단의 `## 미확정 사항` 섹션은 이 문서에서 생성되는 뷰다. 세 곳이 어긋나면 이 문서가 맞다.
|
|
14
|
+
|
|
15
|
+
| 위치 | 역할 | 작성자 |
|
|
16
|
+
|------|------|-----------|
|
|
17
|
+
| 발생 지점 (코드·문서) | `PENDING::<종류>::<slug>` 마커 | 사람 |
|
|
18
|
+
| 이 문서 | 항목별 설명·맥락·참조 | 사람 |
|
|
19
|
+
| 각 문서 `## 미확정 사항` | 해당 문서에 걸린 항목 목록 | 도구 생성 |
|
|
20
|
+
|
|
21
|
+
**종류마다 `##` 섹션이 하나씩 생긴다.** 종류 값은 `config.markers.types` 가 정의하며, 섹션 안은 id 순 정렬이다. 항목 형식은 [`rules.md` §4-2](./rules.md#4-2-관리-문서) 가 갖는다.
|
|
22
|
+
|
|
23
|
+
**섹션 머리 표가 색인이다.** 손으로 고치지 않는다 -- 도구가 항목에서 만든다.
|
|
24
|
+
|
|
25
|
+
## 참조
|
|
26
|
+
|
|
27
|
+
### 문서
|
|
28
|
+
|
|
29
|
+
- [`rules.md`](./rules.md) - §1
|
|
30
|
+
|
|
31
|
+
## 변경 이력
|
|
32
|
+
|
|
33
|
+
| 날짜 | 내용 |
|
|
34
|
+
|-----|-----|
|