@txstack/dev-guide 0.0.0-stage → 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/CHANGELOG.md +9 -0
- package/LICENSE +21 -0
- package/README.md +123 -2
- package/llms.txt +33 -0
- package/package.json +39 -3
- package/process/agents.md +49 -0
- package/process/docs-structure.md +82 -0
- package/process/workflow.md +82 -0
- package/rules/code.md +65 -0
- package/rules/commits.md +61 -0
- package/rules/scripts.md +95 -0
- package/rules/workspace.md +51 -0
- package/templates/CLAUDE.md +32 -0
- package/templates/CURRENT.md +20 -0
- package/templates/DEV_GUIDE_DIFF.md +9 -0
- package/templates/docs-README.md +27 -0
- package/templates/plan.md +42 -0
- package/templates/report.md +27 -0
- package/templates/requirements.md +30 -0
- package/templates/rule.md +5 -0
- package/templates/verification.md +40 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# @txstack/dev-guide
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
첫 판. 판 번호의 뜻과 올릴 때의 절차는 [README](README.md) 「버전을 올릴 때」.
|
|
6
|
+
|
|
7
|
+
- `rules/` — 실행 스크립트 이름 · 커밋 · 작업 공간 · 코드
|
|
8
|
+
- `process/` — docs 여섯 칸 구조 · 요구사항 → 계획 → 구현 → 검증 → 보고 · 사람과 AI 의 몫
|
|
9
|
+
- `templates/` — requirements · plan · verification · report · rule · docs-README · CURRENT · CLAUDE · DEV_GUIDE_DIFF
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 txstack contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,124 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @txstack/dev-guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**프로젝트를 시작할 때 "참고한다" 가 아니라 "따른다" 로 쓰는 개발 기준.**
|
|
4
|
+
실행 스크립트 이름 · 커밋 · 작업 공간 · 코드 규칙과, 요구사항 → 계획 → 구현 → 검증 → 보고로 이어지는
|
|
5
|
+
문서 프로세스, 그리고 그 문서들의 양식이 들어 있다. 런타임 코드가 없다 — 마크다운 묶음이다.
|
|
6
|
+
|
|
7
|
+
## 설치
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
pnpm add -D @txstack/dev-guide # 일반 저장소
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
pnpm add -D -w @txstack/dev-guide # pnpm 모노레포 — 루트에 한 번
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
설치된 버전과 가이드가 늘 같다. 무엇이 바뀌었는지는 함께 설치되는 [CHANGELOG.md](CHANGELOG.md) 에 있다.
|
|
18
|
+
|
|
19
|
+
## 새 프로젝트에 붙이기
|
|
20
|
+
|
|
21
|
+
**이미 있는 파일은 덮어쓰지 않는다.** 아래 명령은 없는 파일만 만들고, 있는 파일은 이름을 알려 준다 — 그 파일은 양식과 비교해 손으로 합친다.
|
|
22
|
+
|
|
23
|
+
**1. 설치** — 위의 [설치](#설치).
|
|
24
|
+
|
|
25
|
+
**2 · 3. 문서 폴더를 만들고 기본 양식을 놓는다** — 저장소 루트에서.
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
G=node_modules/@txstack/dev-guide/templates
|
|
29
|
+
put() { if [ -e "$2" ]; then echo "이미 있다 — 양식과 비교해 손으로 합친다: $2"; else cp "$G/$1" "$2"; fi; }
|
|
30
|
+
mkdir -p docs/project docs/rules docs/requirements docs/plans docs/verification docs/reports
|
|
31
|
+
put docs-README.md docs/README.md
|
|
32
|
+
put CURRENT.md CURRENT.md
|
|
33
|
+
put CLAUDE.md CLAUDE.md
|
|
34
|
+
put CLAUDE.md AGENTS.md
|
|
35
|
+
put DEV_GUIDE_DIFF.md docs/rules/00_DEV_GUIDE_DIFF.md
|
|
36
|
+
put rule.md docs/project/01_PROJECT_OVERVIEW.md
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**4. 프로젝트 정보를 채운다.** `<…>` 자리를 채운다 — `CURRENT.md` 의 지금 상태, `docs/project/01_PROJECT_OVERVIEW.md` 의 서비스 소개,
|
|
40
|
+
`docs/rules/00_DEV_GUIDE_DIFF.md` 의 **따르는 판**(설치한 버전). 다르게 할 것이 없으면 표는 비워 둔다.
|
|
41
|
+
|
|
42
|
+
**5. `CLAUDE.md` · `AGENTS.md` 를 잇는다.** 새로 만들었으면 `<…>` 만 채운다. 이미 있던 파일이면 맨 위에 아래 문단을 넣는다.
|
|
43
|
+
UI 를 `@txstack/ui` 로 짓는다면 그 아래에 `@txstack/ui` 의 `ai/rules.md` 「소비자 프로젝트 시작 묶음」 문단도 넣는다.
|
|
44
|
+
|
|
45
|
+
```md
|
|
46
|
+
## 개발 기준
|
|
47
|
+
|
|
48
|
+
이 프로젝트는 **`@txstack/dev-guide`** 를 따른다. 규칙은 설치된 버전에 있다 —
|
|
49
|
+
`node_modules/@txstack/dev-guide/llms.txt` (목차), `rules/` (스크립트 · 커밋 · 작업 공간 · 코드), `process/` (문서 프로세스 · AI 와 일하는 법).
|
|
50
|
+
dev-guide 와 다르게 하는 것은 [docs/rules/00_DEV_GUIDE_DIFF.md](docs/rules/00_DEV_GUIDE_DIFF.md) 에만 적는다.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**6. 첫 작업을 쓴다.** 번호와 이름을 정하고 양식 셋을 복사한 뒤, `docs/README.md` 의 「작업」 링크를 그 이름으로 고친다.
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
G=node_modules/@txstack/dev-guide/templates
|
|
57
|
+
n=001_first_feature # <작업 번호>_<이름>
|
|
58
|
+
cp "$G/requirements.md" "docs/requirements/$n.md"
|
|
59
|
+
cp "$G/plan.md" "docs/plans/$n.md"
|
|
60
|
+
cp "$G/verification.md" "docs/verification/$n.md"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
양식 안의 `nnn_title.md` 링크도 같은 이름으로 바꾼다. 무엇을 언제 쓰는지는 [process/workflow.md](process/workflow.md).
|
|
64
|
+
|
|
65
|
+
**dev-guide 의 규칙을 프로젝트 문서에 옮겨 적지 않는다** — 옮긴 순간 갈라진다. 다르게 하는 것만 `00_DEV_GUIDE_DIFF.md` 에 적는다.
|
|
66
|
+
|
|
67
|
+
## 버전을 올릴 때
|
|
68
|
+
|
|
69
|
+
판을 올리면 **AI 가 읽는 규칙이 그 자리에서 바뀐다.** 그래서 올리는 것 자체를 작업 하나로 다룬다.
|
|
70
|
+
|
|
71
|
+
1. 설치된 `CHANGELOG.md` 에서 지금 판과 새 판 사이에 바뀐 규칙을 읽는다
|
|
72
|
+
2. `docs/rules/00_DEV_GUIDE_DIFF.md` 와 비교한다 — 예외로 두었던 규칙이 바뀌었나, 새 규칙이 이 프로젝트와 부딪히나
|
|
73
|
+
3. 영향을 본다 — 스크립트 이름 · `docs/` 구조 · 진행 중인 작업 문서 · `CLAUDE.md` 의 문단
|
|
74
|
+
4. 받아들일 것과 예외로 둘 것을 정해 `00_DEV_GUIDE_DIFF.md` 표에 날짜와 함께 적는다
|
|
75
|
+
5. **따르는 판**을 고치고, 받아들인 규칙대로 프로젝트를 맞춘다
|
|
76
|
+
6. 한 커밋에 담는다 — `chore: dev-guide 0.2.0 을 따른다`
|
|
77
|
+
|
|
78
|
+
**이미 복사한 양식은 저절로 바뀌지 않는다.** 설치된 규칙만 바뀐다. 새 작업부터 새 양식을 쓰고, 진행 중인 문서는 그대로 둬도 된다.
|
|
79
|
+
`CURRENT.md` · `docs/README.md` · `CLAUDE.md` 처럼 계속 쓰는 문서는 새 양식과 비교해 필요한 것만 옮긴다.
|
|
80
|
+
|
|
81
|
+
### 판 번호의 뜻
|
|
82
|
+
|
|
83
|
+
| 판 | 무엇이 바뀌나 | 위의 절차 |
|
|
84
|
+
| ------------- | ------------------------------------------------------ | ---------- |
|
|
85
|
+
| patch `0.1.x` | 문구 · 오타 · 예시. 따르는 방법은 그대로 | 필요 없다 |
|
|
86
|
+
| minor `0.x.0` | 규칙을 더하거나 바꾸거나 뺐다 · 양식의 구조가 바뀌었다 | **밟는다** |
|
|
87
|
+
|
|
88
|
+
1.0 이후에는 규칙을 바꾸거나 빼면 major, 더하면 minor, 문구는 patch 다.
|
|
89
|
+
|
|
90
|
+
## 들어 있는 것
|
|
91
|
+
|
|
92
|
+
| 장 | 무엇 |
|
|
93
|
+
| ------------------------------------------------------ | -------------------------------------------------------------------- |
|
|
94
|
+
| [rules/scripts.md](rules/scripts.md) | 실행 스크립트 이름 — `<동작>:<대상>[:<변형>]`, `dev` · `start` 의 뜻 |
|
|
95
|
+
| [rules/commits.md](rules/commits.md) | Conventional Commits + 한글 · 커밋 단위 · 브랜치 · 커밋 훅 |
|
|
96
|
+
| [rules/workspace.md](rules/workspace.md) | pnpm · Node 고정 · `apps/` 와 `packages/` · 의존성 · 환경 변수 |
|
|
97
|
+
| [rules/code.md](rules/code.md) | 파일 · 이름 · TypeScript · import · 화면 · 서버 · 주석 · 테스트 |
|
|
98
|
+
| [process/docs-structure.md](process/docs-structure.md) | `docs/` 여섯 칸 · 파일 이름과 번호 · `CURRENT.md` · 색인 |
|
|
99
|
+
| [process/workflow.md](process/workflow.md) | 요구사항 → 계획 → 구현 → 검증(QA) → 보고, 단계마다 시작 · 끝 조건 |
|
|
100
|
+
| [process/agents.md](process/agents.md) | 사람과 AI 의 몫 · 다시 제안하기 · 증거로 말하기 |
|
|
101
|
+
| [llms.txt](llms.txt) | AI 가 먼저 읽는 목차 |
|
|
102
|
+
| [CHANGELOG.md](CHANGELOG.md) | 판마다 바뀐 규칙 |
|
|
103
|
+
|
|
104
|
+
## 양식
|
|
105
|
+
|
|
106
|
+
| 양식 | 놓는 곳 |
|
|
107
|
+
| ------------------------------------------------ | ----------------------------------------------------- |
|
|
108
|
+
| [requirements.md](templates/requirements.md) | `docs/requirements/nnn_title.md` |
|
|
109
|
+
| [plan.md](templates/plan.md) | `docs/plans/nnn_title.md` |
|
|
110
|
+
| [verification.md](templates/verification.md) | `docs/verification/nnn_title.md` |
|
|
111
|
+
| [report.md](templates/report.md) | `docs/reports/nnn_title.md` |
|
|
112
|
+
| [rule.md](templates/rule.md) | `docs/rules/NN_TITLE.md` · `docs/project/NN_TITLE.md` |
|
|
113
|
+
| [docs-README.md](templates/docs-README.md) | `docs/README.md` |
|
|
114
|
+
| [CURRENT.md](templates/CURRENT.md) | 저장소 루트 `CURRENT.md` |
|
|
115
|
+
| [CLAUDE.md](templates/CLAUDE.md) | 저장소 루트 `CLAUDE.md` · `AGENTS.md` |
|
|
116
|
+
| [DEV_GUIDE_DIFF.md](templates/DEV_GUIDE_DIFF.md) | `docs/rules/00_DEV_GUIDE_DIFF.md` |
|
|
117
|
+
|
|
118
|
+
## 담지 않는 것
|
|
119
|
+
|
|
120
|
+
**도메인 지식 · 특정 서버 · 특정 클라우드의 절차.** 그것은 각 프로젝트의 `docs/project/` · `docs/rules/` 가 갖는다.
|
|
121
|
+
**화면 부품을 고르는 규칙**도 담지 않는다 — `@txstack/ui` 의 `ai/rules.md` 가 갖는다.
|
|
122
|
+
eslint · prettier · commitlint 설정 프리셋은 다음 판에 서브패스로 더한다.
|
|
123
|
+
|
|
124
|
+
MIT
|
package/llms.txt
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# @txstack/dev-guide
|
|
2
|
+
|
|
3
|
+
> 이 프로젝트가 따르는 개발 기준. 실행 스크립트 이름 · 커밋 · 작업 공간 · 코드 규칙, 문서 프로세스(요구사항 → 계획 → 구현 → 검증 → 보고), 문서 양식.
|
|
4
|
+
> 프로젝트가 다르게 정한 것은 그 프로젝트의 docs/rules/00_DEV_GUIDE_DIFF.md 에만 있다. 그 파일이 이 가이드보다 앞선다.
|
|
5
|
+
|
|
6
|
+
## 규칙
|
|
7
|
+
|
|
8
|
+
- [rules/scripts.md](rules/scripts.md): 실행 스크립트 이름 — <동작>:<대상>[:<변형>], dev = 개발 · start = 운영, 루트 공통 스크립트, check 의 뜻
|
|
9
|
+
- [rules/commits.md](rules/commits.md): Conventional Commits + 한글, 커밋 단위, 커밋 · 푸시 · 배포는 요청할 때만, 브랜치, 커밋 훅
|
|
10
|
+
- [rules/workspace.md](rules/workspace.md): pnpm · Node 고정, apps/ 와 packages/, 의존성, link: 를 main 에 올리지 않기, 환경 변수 local · dev · live
|
|
11
|
+
- [rules/code.md](rules/code.md): 파일 · 이름 규칙, TypeScript strict, import 순서와 공개 진입점, 화면 · 서버 계층(부품 고르기는 @txstack/ui 의 ai/rules.md), 주석 · 테스트
|
|
12
|
+
|
|
13
|
+
## 프로세스
|
|
14
|
+
|
|
15
|
+
- [process/docs-structure.md](process/docs-structure.md): docs/ 여섯 칸(project · rules · requirements · plans · verification · reports), NN_TITLE.md 와 nnn_title.md, 작업 번호 공유, CURRENT.md, 색인
|
|
16
|
+
- [process/workflow.md](process/workflow.md): 작업 번호가 필요한가, 요구사항 → 계획 → 구현 → 검증(QA) → 보고 단계마다 시작 · 끝 조건
|
|
17
|
+
- [process/agents.md](process/agents.md): 사람과 AI 의 몫, 판단은 멈추고 묻는다, 그대로 따르지 않고 다시 제안한다, 증거로 말한다, 시작 문장
|
|
18
|
+
|
|
19
|
+
## 양식
|
|
20
|
+
|
|
21
|
+
- [templates/requirements.md](templates/requirements.md): docs/requirements/nnn_title.md — 배경 · 범위 · 수용 기준(AC) · 결정과 미정
|
|
22
|
+
- [templates/plan.md](templates/plan.md): docs/plans/nnn_title.md — 관찰 · 변경 범위 · T1… · 정할 것 · 검증 방법 · 체크리스트
|
|
23
|
+
- [templates/verification.md](templates/verification.md): docs/verification/nnn_title.md — AC 결과 · 증거 · 사용자 확인 체크리스트(QA) · 인계
|
|
24
|
+
- [templates/report.md](templates/report.md): docs/reports/nnn_title.md — 밖에 건네는 문서
|
|
25
|
+
- [templates/rule.md](templates/rule.md): docs/rules/NN_TITLE.md
|
|
26
|
+
- [templates/docs-README.md](templates/docs-README.md): docs/README.md 색인
|
|
27
|
+
- [templates/CURRENT.md](templates/CURRENT.md): 저장소 루트 — 지금 상태 · 다음 할 일
|
|
28
|
+
- [templates/CLAUDE.md](templates/CLAUDE.md): 저장소 루트 — AI 도구가 먼저 읽는 문서
|
|
29
|
+
- [templates/DEV_GUIDE_DIFF.md](templates/DEV_GUIDE_DIFF.md): docs/rules/00_DEV_GUIDE_DIFF.md — dev-guide 와 다른 점
|
|
30
|
+
|
|
31
|
+
## 판
|
|
32
|
+
|
|
33
|
+
- [CHANGELOG.md](CHANGELOG.md): 판마다 바뀐 규칙. 판을 올릴 때의 절차는 README 「버전을 올릴 때」
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@txstack/dev-guide",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Shared development guide — script naming, code and commit rules, a document-driven workflow (requirements → plans → verification → reports) and document templates",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"conventions",
|
|
7
|
+
"guide",
|
|
8
|
+
"workflow",
|
|
9
|
+
"templates",
|
|
10
|
+
"monorepo",
|
|
11
|
+
"ai"
|
|
12
|
+
],
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/code7004/txstack.git",
|
|
17
|
+
"directory": "packages/dev-guide"
|
|
18
|
+
},
|
|
19
|
+
"homepage": "https://github.com/code7004/txstack/tree/main/packages/dev-guide#readme",
|
|
20
|
+
"bugs": "https://github.com/code7004/txstack/issues",
|
|
21
|
+
"files": [
|
|
22
|
+
"README.md",
|
|
23
|
+
"CHANGELOG.md",
|
|
24
|
+
"LICENSE",
|
|
25
|
+
"llms.txt",
|
|
26
|
+
"rules",
|
|
27
|
+
"process",
|
|
28
|
+
"templates"
|
|
29
|
+
],
|
|
30
|
+
"exports": {
|
|
31
|
+
"./llms.txt": "./llms.txt",
|
|
32
|
+
"./rules/*": "./rules/*",
|
|
33
|
+
"./process/*": "./process/*",
|
|
34
|
+
"./templates/*": "./templates/*",
|
|
35
|
+
"./package.json": "./package.json",
|
|
36
|
+
"./CHANGELOG.md": "./CHANGELOG.md",
|
|
37
|
+
"./README.md": "./README.md"
|
|
38
|
+
},
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public"
|
|
41
|
+
}
|
|
6
42
|
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# 사람과 AI 가 함께 일하는 법
|
|
2
|
+
|
|
3
|
+
> 언제 보나: AI 코딩 도구(Claude Code · Codex 등)에게 일을 맡길 때. AI 도구가 작업을 시작할 때.
|
|
4
|
+
|
|
5
|
+
## 1. 몫
|
|
6
|
+
|
|
7
|
+
| 누가 | 맡는 것 |
|
|
8
|
+
| ---- | ------------------------------------------------------------------------------------------- |
|
|
9
|
+
| 사람 | **방향 · 우선순위 · 정책 · 판단.** 범위 합의 · 공개 API 합의 · 화면 확인 · 커밋 · 배포 요청 |
|
|
10
|
+
| AI | 조사 · 초안 · 구현 · 테스트 · 검증 기록 · 문서 정합화 |
|
|
11
|
+
|
|
12
|
+
- **판단이 필요한 일은 사람의 승인 없이 넘어가지 않는다.** AI 는 근거와 추천안을 들고 멈춘다
|
|
13
|
+
- **첫 번은 사람이, 반복은 AI 가.** 새 패턴의 첫 구현은 사람이 하고, 그것이 본보기가 된 뒤의 반복 · 테스트 · 정리를 AI 가 맡는다
|
|
14
|
+
- 도구가 둘이면(예: Codex 가 문서, Claude Code 가 구현) 그 나눔을 프로젝트의 `00_DEV_GUIDE_DIFF.md` 에 적는다
|
|
15
|
+
- 한 폴더에서 두 도구가 같은 파일을 동시에 고치지 않는다
|
|
16
|
+
|
|
17
|
+
## 2. 그대로 따르지 않고 다시 제안한다
|
|
18
|
+
|
|
19
|
+
지시 · 계획 문서 · AI 의 이전 판단은 **출발점**이다.
|
|
20
|
+
|
|
21
|
+
- 지시한 방식이 낡았거나, 오류 · 보안 문제 · **사실과 다른 전제**가 있거나, 더 단순하고 안전한 길이 있으면 **구현 전에** 다시 제안한다
|
|
22
|
+
- 제안에는 문제 · 근거(읽은 코드 · 문서 · 실행 결과) · 대안 · 각 안의 영향(변경량 · 위험 · 되돌리기) · 추천안
|
|
23
|
+
- 사람이 알고 고른 방식이면 따르고, 결정과 날짜를 기록한다. 같은 제안을 이유 없이 되풀이하지 않는다
|
|
24
|
+
- 판단을 기다리는 동안 그와 무관한 일은 계속한다
|
|
25
|
+
|
|
26
|
+
## 3. 되돌리기 어려운 일은 요청할 때만
|
|
27
|
+
|
|
28
|
+
커밋 · 푸시 · 배포 · `npm publish` · 데이터 삭제 · 외부로 보내는 일(메일 · 문자 · 실제 API 호출).
|
|
29
|
+
프로젝트가 다르게 정했으면 `00_DEV_GUIDE_DIFF.md` 에 결정과 날짜가 있어야 한다.
|
|
30
|
+
|
|
31
|
+
- 기존 변경을 되돌리지 않는다. 관련 없는 파일을 건드리지 않는다
|
|
32
|
+
- 지우기 전에 무엇을 지우는지 본다
|
|
33
|
+
|
|
34
|
+
## 4. 증거로 말한다
|
|
35
|
+
|
|
36
|
+
- "됐다" 고 쓰기 전에 실행한다. 실행한 명령과 결과를 남긴다
|
|
37
|
+
- 통과 · 실패 · 미실행을 나눈다. 확인하지 못한 것은 그렇다고 쓴다
|
|
38
|
+
- 문서에 "구현 완료" 라고 쓰는 것과 실제로 구현 · 검증한 것을 구분한다
|
|
39
|
+
- 빌드가 만든 산출물 · 임시 파일이 작업 트리에 남지 않았는지 `git status` 로 본다
|
|
40
|
+
|
|
41
|
+
## 5. AI 도구의 시작 문장
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
CLAUDE.md · CURRENT.md · docs/README.md 를 읽고, CURRENT.md 「다음 할 일」의 계획에서 다음 미완료 단계를 해줘.
|
|
45
|
+
지시나 계획에 낡은 기술 · 오류 · 틀린 전제가 보이면 구현 전에 근거와 대안을 들어 다시 제안해.
|
|
46
|
+
판단이 필요하면 멈추고 물어.
|
|
47
|
+
실행한 명령 · 결과 · 남은 결정 · 다음 할 일을 같은 번호 verification 에 남기고, CURRENT.md 와 README 의 명령을 맞춰.
|
|
48
|
+
커밋 · 푸시 · 배포는 내가 요청할 때만.
|
|
49
|
+
```
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# docs 폴더 구조
|
|
2
|
+
|
|
3
|
+
> 언제 보나: 프로젝트를 시작할 때, 새 문서를 어디에 둘지 정할 때.
|
|
4
|
+
|
|
5
|
+
## 1. 여섯 칸
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
docs/
|
|
9
|
+
README.md 색인 — 읽는 순서 · 작업 목록
|
|
10
|
+
project/ 이 서비스가 무엇인가 NN_TITLE.md 상시
|
|
11
|
+
rules/ 늘 지키는 개발 규약 NN_TITLE.md 상시
|
|
12
|
+
requirements/ 무엇을 왜 만드나 · 수용 기준 nnn_title.md 작업
|
|
13
|
+
plans/ 어떻게 만드나 · 체크리스트 nnn_title.md 작업
|
|
14
|
+
verification/ 했는가 — 증거 · QA · 인계 nnn_title.md 작업
|
|
15
|
+
reports/ 밖에 건네는 문서 nnn_title.md 필요할 때
|
|
16
|
+
CURRENT.md 지금 어디까지 왔나 (저장소 루트)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
| 칸 | 담는 것 | 담지 않는 것 |
|
|
20
|
+
| --------------- | ---------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
21
|
+
| `project/` | 서비스 목적 · 화면 목록 · 데이터 · API 계약 · 서버 구조 · 운영 절차 · 로드맵 | 작업 하나의 진행 기록 |
|
|
22
|
+
| `rules/` | 프로젝트 고유의 규약 · `00_DEV_GUIDE_DIFF.md` | dev-guide 에 이미 있는 규칙을 옮겨 적지 않는다 |
|
|
23
|
+
| `requirements/` | 배경 · 범위 · 수용 기준(AC ID) · 미정 사항 | 구현 방법 |
|
|
24
|
+
| `plans/` | 관찰 · 변경 범위 · 순서 · 검증 방법 · 마지막 절에 체크리스트 | 실행 결과 |
|
|
25
|
+
| `verification/` | AC 별 증거 · 실행한 명령과 결과 · 사용자 확인 목록(QA) · 인계 | 계획 |
|
|
26
|
+
| `reports/` | 운영진 · 다른 부서 · 외부 담당자에게 **그대로 건넬** 문서 | 개발 인계 · 실행 증거 (링크만 한다) |
|
|
27
|
+
|
|
28
|
+
**작업 문서를 쓰는 순서는 [workflow.md](workflow.md) 가 갖는다.**
|
|
29
|
+
|
|
30
|
+
## 2. 파일 이름 · 번호
|
|
31
|
+
|
|
32
|
+
- **상시 문서** (`project/` · `rules/`): `NN_TITLE.md` — 두 자리 일련번호 + 대문자. `03_DATA_AND_API.md`
|
|
33
|
+
- **작업 문서** (`requirements/` · `plans/` · `verification/` · `reports/`): `nnn_title.md` — 세 자리 작업 번호 + 소문자. `008_reply_implementation.md`
|
|
34
|
+
- **한 작업은 네 칸에서 같은 번호를 쓴다.** `requirements/008_…` → `plans/008_…` → `verification/008_…`
|
|
35
|
+
- 새 작업은 **다음 빈 번호**를 쓴다. 뜻이 달라질 만큼 커지면 새 번호를 연다
|
|
36
|
+
- 한 작업 안의 하위 단계는 문서 안의 절(`T1` · `T2`)로 나눈다. 파일을 쪼개야 하면 `024-2_…` 처럼 붙인다
|
|
37
|
+
- 진행 보고처럼 **계속 고쳐 쓰는 전달 문서**는 `reports/000_progress_report.md` 하나로 둔다
|
|
38
|
+
- 파일 · 폴더 이름은 영문, 본문은 한글
|
|
39
|
+
|
|
40
|
+
## 3. 저장소 루트
|
|
41
|
+
|
|
42
|
+
| 파일 | 담는 것 |
|
|
43
|
+
| ------------------------- | ----------------------------------------------------------------------------------------- |
|
|
44
|
+
| `README.md` | 무엇인지 · 설치 · 실행 명령 · `docs/README.md` 링크. 짧게 |
|
|
45
|
+
| `CLAUDE.md` · `AGENTS.md` | AI 도구가 먼저 읽는 것 — "dev-guide 를 따른다" 문단 · 프로젝트 고유 규칙 요약 · 읽을 문서 |
|
|
46
|
+
| `CURRENT.md` | 지금 상태 · 진행 중인 작업 · 다음 할 일. **상태는 여기에만 쓴다** |
|
|
47
|
+
|
|
48
|
+
`CURRENT.md` 는 고쳐 쓴다 — 지난 상태는 git 이 갖는다. 위에 최신을 둔다.
|
|
49
|
+
|
|
50
|
+
## 4. 문서를 쓰는 법
|
|
51
|
+
|
|
52
|
+
- **첫머리에 기준일과 상태를 쓴다.** `기준일: 2026-11-17. 상태: 합의 전 제안.`
|
|
53
|
+
- **사실 · 결정 · 제안 · 미정을 구분한다.** 결정에는 날짜와 누가 정했는지를 붙인다 — `(2026-10-26 사용자 결정)`
|
|
54
|
+
- **실행한 것과 하지 않은 것을 구분한다.** 미실행 · 실패 · 통과. 빈 보고서는 완료 보고서가 아니다
|
|
55
|
+
- **옮겨 적지 않고 링크한다.** 같은 내용이 두 곳에 있으면 한쪽이 낡는다
|
|
56
|
+
- **지금과 달라진 문서는 고쳐 쓴다.** 고친 이력은 git 이 갖는다. 이력으로 남길 가치가 있는 판단만 "왜 바꿨나" 로 남긴다
|
|
57
|
+
- 상시 문서 첫머리에 **언제 보나** 를 한 줄로 쓴다
|
|
58
|
+
|
|
59
|
+
## 5. 색인 — `docs/README.md`
|
|
60
|
+
|
|
61
|
+
```md
|
|
62
|
+
# 개발 문서 색인
|
|
63
|
+
|
|
64
|
+
기준일: YYYY-MM-DD.
|
|
65
|
+
|
|
66
|
+
## 문서 구조
|
|
67
|
+
|
|
68
|
+
(1장의 표)
|
|
69
|
+
|
|
70
|
+
## 읽는 순서
|
|
71
|
+
|
|
72
|
+
- [프로젝트 개요](project/01_PROJECT_OVERVIEW.md)
|
|
73
|
+
- …
|
|
74
|
+
|
|
75
|
+
## 작업
|
|
76
|
+
|
|
77
|
+
### 008 — 11월 회신 반영
|
|
78
|
+
|
|
79
|
+
[요구사항](requirements/008_reply_decisions.md) → [계획](plans/008_reply_implementation.md) → [검증](verification/008_reply_implementation.md)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
문서를 더하거나 지우면 색인을 같이 고친다. 양식: [templates/docs-README.md](../templates/docs-README.md).
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# 작업 흐름 — 요구사항 → 계획 → 구현 → 검증 → 보고
|
|
2
|
+
|
|
3
|
+
> 언제 보나: 작업 하나를 시작할 때, 끝났다고 말하기 전에.
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
요구사항 ──▶ 계획 ──▶ 구현 ──▶ 검증(QA) ──▶ 보고(필요할 때)
|
|
7
|
+
requirements plans 코드 verification reports
|
|
8
|
+
└─────────── 같은 작업 번호 nnn ───────────┘
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 0. 작업 번호가 필요한가
|
|
12
|
+
|
|
13
|
+
| 일의 크기 | 문서 |
|
|
14
|
+
| ------------------------------------------------------- | ------------------------------------------- |
|
|
15
|
+
| 오타 · 한 줄 수정 · 의존성 올리기 · 이름 정리 | **문서 없음.** 커밋 메시지가 기록이다 |
|
|
16
|
+
| 결함 하나 · 작은 기능 하나 (한 번에 끝나고 판단이 없다) | `verification/` 하나에 무엇을 · 증거 · 인계 |
|
|
17
|
+
| 판단이 필요하거나 여러 단계 · 여러 날에 걸치는 일 | **네 단계 전부** — 아래 1~5 |
|
|
18
|
+
|
|
19
|
+
애매하면 번호를 연다. 번호 없이 시작한 일이 커지면 그때 연다.
|
|
20
|
+
|
|
21
|
+
## 1. 요구사항 — `requirements/nnn_title.md`
|
|
22
|
+
|
|
23
|
+
**무엇을 왜 만드나.** 구현 방법은 쓰지 않는다.
|
|
24
|
+
|
|
25
|
+
| 시작 | 끝 (다음으로 가는 조건) |
|
|
26
|
+
| ------------------------------ | -------------------------------------------------------------------------------- |
|
|
27
|
+
| 요청 · 회의 · 결함 보고를 받음 | 수용 기준(AC)마다 ID 가 있고, 미정 사항이 표시되고, **사용자가 범위에 합의**했다 |
|
|
28
|
+
|
|
29
|
+
- 수용 기준은 **확인할 수 있는 문장**으로 쓴다 — "빠르게" 가 아니라 "목록 1,000건이 2초 안에 그려진다"
|
|
30
|
+
- ID 를 붙인다(`AC01`). 계획 · 검증이 같은 ID 를 쓴다
|
|
31
|
+
- 확정 · 제안 · 미정을 구분하고, 결정에는 날짜를 붙인다
|
|
32
|
+
|
|
33
|
+
## 2. 계획 — `plans/nnn_title.md`
|
|
34
|
+
|
|
35
|
+
**어떻게 만드나.**
|
|
36
|
+
|
|
37
|
+
| 시작 | 끝 |
|
|
38
|
+
| ----------------- | --------------------------------------------------------------------------- |
|
|
39
|
+
| 요구사항이 합의됨 | 순서 · 변경 범위 · 검증 방법이 있고, **판단이 필요한 것은 사용자가 골랐다** |
|
|
40
|
+
|
|
41
|
+
- 먼저 **지금 코드를 읽고 관찰한 것**을 쓴다. 전제가 사실과 다르면 여기서 멈추고 알린다
|
|
42
|
+
- 단계를 `T1` · `T2` 로 나누고, 각 단계가 어느 AC 를 채우는지 적는다
|
|
43
|
+
- 공개 API · 화면 모양처럼 되돌리기 어려운 것은 **예제 코드로 먼저 합의**한다
|
|
44
|
+
- **마지막 절은 체크리스트다** — 구현하며 지워 나간다
|
|
45
|
+
|
|
46
|
+
## 3. 구현
|
|
47
|
+
|
|
48
|
+
| 시작 | 끝 |
|
|
49
|
+
| ------------- | -------------------------------------------------------- |
|
|
50
|
+
| 계획이 합의됨 | 계획의 단계가 끝나고, `pnpm check` · `build` 가 통과한다 |
|
|
51
|
+
|
|
52
|
+
- **한 번에 하나.** 작업 단위 하나를 끝까지 관통한 뒤 다음으로 간다. 계층별로 몰아서 하지 않는다
|
|
53
|
+
- 구현 중 계획과 다른 판단이 필요하면 **멈추고 묻는다.** 옮긴 뒤에 고치면 무엇이 원본이고 무엇이 판단이었는지 흐려진다
|
|
54
|
+
- 계획을 바꿨으면 계획 문서를 고친다
|
|
55
|
+
|
|
56
|
+
## 4. 검증 · QA — `verification/nnn_title.md`
|
|
57
|
+
|
|
58
|
+
**했는가.** 증거로 말한다.
|
|
59
|
+
|
|
60
|
+
| 시작 | 끝 |
|
|
61
|
+
| ---------------- | -------------------------------------------------------------- |
|
|
62
|
+
| 구현 단계가 끝남 | AC 마다 통과 · 실패 · 미실행이 증거와 함께 있고, 인계가 쓰였다 |
|
|
63
|
+
|
|
64
|
+
- **AC 별로** 무엇을 해서 무엇을 봤는지 — 실행한 명령 · 결과 · 화면 캡처
|
|
65
|
+
- **실행하지 않은 것을 했다고 쓰지 않는다.** 확인 못 한 것은 "미실행" 과 이유
|
|
66
|
+
- 사람이 직접 봐야 하는 것은 **사용자 확인 체크리스트**로 남긴다 — 이것이 QA 다
|
|
67
|
+
- 끝에 **인계**: 바뀐 것 · 남은 것 · 남은 결정 · 다음 작업 · 배포 여부
|
|
68
|
+
|
|
69
|
+
## 5. 보고 — `reports/nnn_title.md` (필요할 때만)
|
|
70
|
+
|
|
71
|
+
**밖에 건네는 문서.** 운영진 · 다른 부서 · 외부 담당자가 읽는다.
|
|
72
|
+
|
|
73
|
+
- 첫머리에 **읽는 사람**을 쓴다. 쉬운 말로, 짧게. 커밋 번호 · 코드 이름 · 파일 경로는 꼭 필요할 때만
|
|
74
|
+
- 증거 · 인계 · 계산 규칙은 옮겨 적지 않고 링크한다
|
|
75
|
+
- 진행 보고는 `reports/000_progress_report.md` 한 장을 계속 고쳐 쓴다 — 맨 위 "지금 상태", 아래로 날짜별 기록(최신이 위)
|
|
76
|
+
|
|
77
|
+
## 6. 끝낼 때마다
|
|
78
|
+
|
|
79
|
+
- [ ] `CURRENT.md` — 지금 상태 · 다음 할 일
|
|
80
|
+
- [ ] `docs/README.md` — 새 문서를 색인에
|
|
81
|
+
- [ ] README 의 실행 명령이 실제 `package.json` 과 맞는가
|
|
82
|
+
- [ ] 커밋은 요청이 있을 때 ([rules/commits.md](../rules/commits.md))
|
package/rules/code.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# 코드
|
|
2
|
+
|
|
3
|
+
> 언제 보나: 코드를 쓰기 전에. 도메인 규칙은 각 프로젝트의 `docs/rules/` 가 갖는다.
|
|
4
|
+
|
|
5
|
+
## 1. 원칙
|
|
6
|
+
|
|
7
|
+
- **읽히는 것이 먼저다.** 짧은 것보다 뜻이 보이는 것
|
|
8
|
+
- **있는 구조를 먼저 따른다.** 새 패턴은 쓰는 곳이 둘 이상일 때
|
|
9
|
+
- **명시적으로.** 숨은 전역 · 마법 같은 자동 등록보다 import 와 인자
|
|
10
|
+
- **쓰지 않는 것을 미리 만들지 않는다.** 추상화 · 옵션 · 공용 패키지 모두
|
|
11
|
+
|
|
12
|
+
## 2. 파일 · 이름
|
|
13
|
+
|
|
14
|
+
다섯 프로젝트에서 실제로 쓰는 방식이다 (2026-11-17 측정).
|
|
15
|
+
|
|
16
|
+
| 대상 | 규칙 | 예 |
|
|
17
|
+
| ---------------------------- | --------------------------------- | ---------------------------------------------- |
|
|
18
|
+
| React 컴포넌트 파일 | 컴포넌트 이름 그대로 — PascalCase | `UserListPage.tsx` · `TxButton.tsx` |
|
|
19
|
+
| 훅 · 함수 모듈 (프런트) | camelCase | `useUserFilter.ts` · `formatPrice.ts` |
|
|
20
|
+
| NestJS | Nest 관례 — `kebab-이름.종류.ts` | `payout-baseline.service.ts` |
|
|
21
|
+
| 변수 · 함수 | camelCase | |
|
|
22
|
+
| 상수 | UPPER_SNAKE_CASE | `MAX_PAGE_SIZE` |
|
|
23
|
+
| 타입 · 인터페이스 · 컴포넌트 | PascalCase | |
|
|
24
|
+
| 폴더 | 담은 것의 이름 규칙을 따른다 | 컴포넌트 하나면 `TxButton/`, 묶음이면 `pages/` |
|
|
25
|
+
|
|
26
|
+
**이름은 무엇인지를 말한다.** `data` · `info` · `temp` · `handle` 만으로 짓지 않는다.
|
|
27
|
+
|
|
28
|
+
## 3. TypeScript
|
|
29
|
+
|
|
30
|
+
- `strict: true`. `any` 를 쓰면 그 줄에 이유를 남긴다
|
|
31
|
+
- 밖으로 내보내는 함수 · 컴포넌트의 인자와 반환은 타입을 적는다
|
|
32
|
+
- 앱 전역(ambient) 타입 · 전역 변수에 기대지 않는다 — 옮기면 깨진다
|
|
33
|
+
- API 응답 · DTO 타입과 화면 상태 타입을 나눈다. ORM 타입(Prisma 등)을 API 밖으로 그대로 내보내지 않는다
|
|
34
|
+
|
|
35
|
+
## 4. import
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { useState } from "react"; // 1. 외부 라이브러리
|
|
39
|
+
import { TxButton } from "@txstack/ui"; // 2. 공용 패키지
|
|
40
|
+
import { usePayouts } from "@/features/payout"; // 3. 앱 안 (별칭)
|
|
41
|
+
import { Row } from "./Row"; // 4. 같은 폴더
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- 패키지는 **공개 진입점만** import 한다 (`@txstack/ui`, `@txstack/hooks/useObjectState`). `dist/` 안을 직접 가리키지 않는다
|
|
45
|
+
- 상대 경로가 `../../..` 처럼 깊어지면 `@/` 별칭을 쓴다
|
|
46
|
+
|
|
47
|
+
## 5. 화면 (React)
|
|
48
|
+
|
|
49
|
+
- **UI 를 `@txstack/ui` 로 짓는다면, 어떤 부품을 고르고 어떻게 꾸미는지는 그 패키지의 AI 가이드가 갖는다** —
|
|
50
|
+
`node_modules/@txstack/ui/ai/rules.md`. 여기에 다시 적지 않는다 (부품과 함께 바뀌므로)
|
|
51
|
+
- 화면(page)은 조립만 한다. 데이터 가져오기 · 변환은 훅이나 데이터 계층으로
|
|
52
|
+
- 전역 상태는 최소로. URL 에 둘 수 있는 상태(필터 · 페이지)는 URL 에
|
|
53
|
+
|
|
54
|
+
## 6. 서버
|
|
55
|
+
|
|
56
|
+
- 요청 핸들러(controller)는 얇게 — 입력 검증과 서비스 호출만
|
|
57
|
+
- 업무 규칙은 서비스에, DB 접근은 그 아래 계층에
|
|
58
|
+
- 입력은 경계에서 검증한다(DTO · 스키마)
|
|
59
|
+
- 외부 서비스는 인터페이스 뒤에 두고, 개발 · 시험에는 합성 구현을 꽂는다
|
|
60
|
+
|
|
61
|
+
## 7. 주석 · 테스트
|
|
62
|
+
|
|
63
|
+
- 주석은 **왜**를 쓴다. 무엇을 하는지는 코드가 말한다. 사실이 아닌 주석은 지운다
|
|
64
|
+
- 결함을 고치면 그 결함을 다시 잡는 테스트를 같이 넣는다
|
|
65
|
+
- 테스트 이름은 동작으로 쓴다 — "빈 값이면 0 을 그린다"
|
package/rules/commits.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# 커밋 · 브랜치
|
|
2
|
+
|
|
3
|
+
> 언제 보나: 커밋 · 브랜치 · 푸시 전에.
|
|
4
|
+
|
|
5
|
+
## 1. 커밋 메시지 — Conventional Commits + 한글
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
<type>(<scope>): <무엇을 하는지 한 줄>
|
|
9
|
+
|
|
10
|
+
<왜 — 무엇이 문제였고 무엇을 골랐나. 필요할 때만>
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
feat: TxDropdown 다중선택 지원
|
|
15
|
+
fix(hooks): useUrlQuery 가 주소 모양과 상관없이 선언한 타입을 지킨다
|
|
16
|
+
chore: txstack 을 link 대신 npm 배포본(^0.1.2)으로 설치한다
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
| type | 언제 |
|
|
20
|
+
| ---------- | ------------------------------ |
|
|
21
|
+
| `feat` | 쓰는 사람에게 보이는 새 기능 |
|
|
22
|
+
| `fix` | 결함 수정 |
|
|
23
|
+
| `refactor` | 동작은 그대로, 구조만 |
|
|
24
|
+
| `docs` | 문서만 |
|
|
25
|
+
| `test` | 테스트만 |
|
|
26
|
+
| `chore` | 의존성 · 설정 · 도구 · 버전 |
|
|
27
|
+
| `style` | 포맷만 (`pnpm format` 결과 등) |
|
|
28
|
+
|
|
29
|
+
- **제목은 한글로, 무엇을 하는지 쓴다.** "수정" · "업데이트" 처럼 내용 없는 말을 쓰지 않는다
|
|
30
|
+
- `scope` 는 고르게 쓸 때만 — 모노레포의 패키지 · 앱 이름(`fix(hooks):`, `feat(dev):`)
|
|
31
|
+
- 본문은 **왜**를 쓴다. 무엇을 바꿨는지는 diff 가 갖는다
|
|
32
|
+
- commitlint 는 `@commitlint/config-conventional` 에 본문 줄 길이 제한을 끈다 — 표 · 목록 · 링크를 쓸 수 있게
|
|
33
|
+
|
|
34
|
+
## 2. 커밋 단위
|
|
35
|
+
|
|
36
|
+
- **커밋 하나 = 작업 단위 하나.** 기능 하나 · 결함 하나. 계층별로 몰아서(모든 스크립트, 모든 문서) 커밋하지 않는다
|
|
37
|
+
- **저장소 둘을 한 일로 묶지 않는다.** 라이브러리와 그것을 쓰는 프로젝트는 각자 커밋한다
|
|
38
|
+
- 포맷만 바뀐 대량 변경은 따로 커밋한다 — 리뷰에서 내용 변경이 묻힌다
|
|
39
|
+
- 관련 없는 diff 는 담지 않는다. 남이 하던 변경을 되돌리지 않는다
|
|
40
|
+
|
|
41
|
+
## 3. 커밋 · 푸시 · 배포는 요청할 때만
|
|
42
|
+
|
|
43
|
+
**기본값은 "사람이 요청할 때만" 이다** — AI 가 스스로 커밋 · 푸시 · 배포 · `npm publish` 하지 않는다. 되돌리기 어렵기 때문이다.
|
|
44
|
+
프로젝트가 다르게 정하면(예: 검사가 통과하면 스스로 커밋 · 푸시) 그 결정과 날짜를 `docs/rules/00_DEV_GUIDE_DIFF.md` 에 적는다.
|
|
45
|
+
|
|
46
|
+
## 4. 브랜치
|
|
47
|
+
|
|
48
|
+
| 브랜치 | 쓰임 |
|
|
49
|
+
| -------------------------------------- | --------------------------------------- |
|
|
50
|
+
| `main` | 배포되는 기준. 서버가 pull 하는 곳 |
|
|
51
|
+
| `feat/<짧은-이름>` · `fix/<짧은-이름>` | 여러 커밋에 걸치거나 검토가 필요한 작업 |
|
|
52
|
+
|
|
53
|
+
- 혼자 하는 작은 수정은 `main` 에 바로 커밋해도 된다. 서버가 `main` 을 pull 하면 **배포 전에 깨지지 않는 상태**만 올린다
|
|
54
|
+
- **로컬 경로(`link:` · `file:../..`)가 든 `package.json` · lockfile 을 `main` 에 올리지 않는다** — 서버의 `pnpm install --frozen-lockfile` 이 깨진다
|
|
55
|
+
|
|
56
|
+
## 5. 커밋 훅
|
|
57
|
+
|
|
58
|
+
`husky` + `lint-staged` 로 **스테이징한 파일만** `eslint --fix` · `prettier --write` 한다.
|
|
59
|
+
|
|
60
|
+
- 전체 검사(`pnpm check`)는 훅에 두지 않는다. 느리면 사람이 훅을 끈다
|
|
61
|
+
- 훅을 건너뛰지 않는다(`--no-verify` 금지). 훅이 실패하면 원인을 고친다
|
package/rules/scripts.md
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# 실행 스크립트 이름
|
|
2
|
+
|
|
3
|
+
> 언제 보나: 새 프로젝트의 `package.json` 을 짤 때, 스크립트를 더하거나 이름을 바꿀 때.
|
|
4
|
+
|
|
5
|
+
**한 줄 규칙: `<동작>:<대상>[:<변형>]`.** 동작이 앞에 온다. `dev:frontend`, `build:frontend:live`, `deploy:backend:dev`.
|
|
6
|
+
|
|
7
|
+
## 1. 이름 순서
|
|
8
|
+
|
|
9
|
+
| 형식 | 예 | 언제 |
|
|
10
|
+
| ---------------------- | ------------------------------------------------ | -------------------------------------------- |
|
|
11
|
+
| `<동작>` | `dev` · `build` · `check` | 모든 앱 · 패키지를 대상으로 할 때 |
|
|
12
|
+
| `<동작>:<대상>` | `dev:frontend` · `build:api` · `start:worker` | 앱 하나를 다룰 때. 대상은 `apps/` 폴더 이름 |
|
|
13
|
+
| `<동작>:<대상>:<변형>` | `build:frontend:live` · `dev:api:sms-synthetic` | 같은 일의 모드 · 환경 · 옵션 |
|
|
14
|
+
| `<동작>:<변형>` | `build:watch` · `lint:fix` · `format:check` | 대상 없이 모드만 다를 때 |
|
|
15
|
+
| `<도구>:<동작>` (예외) | `db:migrate` · `docker:up` · `changeset:version` | 앱이 아닌 **도구 · 하위 시스템**의 명령 묶음 |
|
|
16
|
+
|
|
17
|
+
**도구 이름이 앞에 오는 것만 예외다.** `db:*` · `docker:*` 는 앱이 아니라 묶음 이름이다. 앱 이름을 앞에 두지 않는다 —
|
|
18
|
+
`frontend:build` 가 아니라 `build:frontend`. 도구 이름이 앱 이름과 같으면(`admin` 앱과 `admin:create`) 동작이 앞에 오게 바꾼다(`create:admin-user`).
|
|
19
|
+
|
|
20
|
+
**왜 동작이 앞인가.** pnpm 은 정규식으로 같은 앞부분을 한 번에 돌린다 — `pnpm run "/^dev:(frontend|backend)$/"`.
|
|
21
|
+
동작이 앞에 있어야 "dev 전부", "build 전부" 로 묶인다. 널리 쓰이는 오픈소스 36곳(Next.js · Supabase · Cal.com · n8n ·
|
|
22
|
+
Payload · MUI · NestJS · Prisma …)의 루트 `package.json` 에서 앱 이름이 들어간 스크립트는 동작-앞 67 · 앱-앞 14 였다(2026-11-17 조사).
|
|
23
|
+
|
|
24
|
+
## 2. 동작 사전 — 같은 낱말은 늘 같은 뜻
|
|
25
|
+
|
|
26
|
+
| 동작 | 뜻 | 하지 않는 것 |
|
|
27
|
+
| -------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|
|
28
|
+
| `dev` | **개발 실행.** 파일을 고치면 다시 뜬다 (vite · nodemon · `nest start --watch`) | lint 를 먼저 돌리지 않는다 — 걸리면 서버가 안 뜬다 |
|
|
29
|
+
| `start` | **운영 실행.** 빌드한 결과를 그대로 띄운다 (`node dist/main`) | 감시(watch) · 개발 도구를 쓰지 않는다 |
|
|
30
|
+
| `build` | 배포할 결과를 만든다 | |
|
|
31
|
+
| `preview` | 빌드 결과를 로컬에서 띄워 본다 | |
|
|
32
|
+
| `lint` | eslint | 고치지 않는다 (`lint:fix` 가 고친다) |
|
|
33
|
+
| `typecheck` | `tsc --noEmit` | |
|
|
34
|
+
| `test` | 테스트를 한 번 돈다 | 감시하지 않는다 (`test:watch`) |
|
|
35
|
+
| `format` | prettier 로 고친다 | (`format:check` 는 고치지 않고 확인만) |
|
|
36
|
+
| `check` | 커밋 · 머지 전에 도는 검사 묶음 — 아래 3장 | |
|
|
37
|
+
| `deploy` | 배포한다 | 빌드를 빠뜨리지 않는다 (`deploy:x` 가 `build:x` 를 부른다) |
|
|
38
|
+
| `clean` | `node_modules` 등 만든 것을 지운다 | **`pnpm store prune` 을 `clean` 이라 부르지 않는다** — PC 전체의 저장소를 지운다 |
|
|
39
|
+
| `status` · `logs` · `tail` | 서버 상태 · 최근 로그 · 실시간 로그 | `watch` 라 부르지 않는다 — "다시 빌드" 와 헷갈린다 |
|
|
40
|
+
|
|
41
|
+
`dev` 와 `start` 의 뜻은 Next.js · Vite 의 기본 템플릿과 같다. `start` 를 개발 서버로 쓰던 것은 Create React App 시절의 관행이다.
|
|
42
|
+
|
|
43
|
+
**같은 일을 하는 이름을 둘 두지 않는다.** `lint:frontend` 가 있으면 `frontend:lint` 를 지운다.
|
|
44
|
+
|
|
45
|
+
## 3. 루트에 늘 있는 것
|
|
46
|
+
|
|
47
|
+
| 스크립트 | 하는 일 |
|
|
48
|
+
| ------------------------- | --------------------------------------------------------------------------- |
|
|
49
|
+
| `dev` | 개발 프로세스를 전부 같이 띄운다 — 5장의 예처럼 `pnpm run` 에 정규식을 준다 |
|
|
50
|
+
| `build` | 전부 빌드한다 — `pnpm -r build` |
|
|
51
|
+
| `lint` · `lint:fix` | 루트에서 eslint 한 번 (설정은 루트가 갖는다) |
|
|
52
|
+
| `typecheck` | `pnpm -r typecheck` |
|
|
53
|
+
| `test` | 테스트가 있으면 — `pnpm -r test` 또는 `vitest run` |
|
|
54
|
+
| `format` · `format:check` | prettier |
|
|
55
|
+
| `check` | `lint` + `typecheck` + `format:check` (+ `test`) |
|
|
56
|
+
| `clean` | 운영체제와 상관없이 도는 node 스크립트로 (PowerShell · bash 전용 금지) |
|
|
57
|
+
|
|
58
|
+
**`check` 에 `test` 를 넣는 기준** — 외부 서비스(DB · Docker) 없이 돌면 넣는다. 아니면 빼고 CI 가 따로 돈다.
|
|
59
|
+
`format:check` 를 처음 넣을 때는 **`pnpm format` 결과를 커밋 하나로 먼저 담는다** — 안 그러면 `check` 가 바로 깨진다.
|
|
60
|
+
|
|
61
|
+
앱 하나만 다루는 명령은 `pnpm --filter <앱> <동작>` 으로도 부를 수 있다. 루트에는 **자주 쓰는 것만** 줄임 명령으로 둔다.
|
|
62
|
+
|
|
63
|
+
## 4. 앱 안의 이름
|
|
64
|
+
|
|
65
|
+
앱의 `package.json` 은 도구의 표준 이름만 쓴다 — `dev` · `build` · `start` · `preview` · `lint` · `typecheck` · `test`.
|
|
66
|
+
모드는 변형으로 붙인다 — `build:dev` · `build:live` · `dev:debug` · `start:worker`.
|
|
67
|
+
|
|
68
|
+
## 5. 예 — 프런트 · 백엔드 두 앱
|
|
69
|
+
|
|
70
|
+
```jsonc
|
|
71
|
+
// 루트 package.json
|
|
72
|
+
{
|
|
73
|
+
"dev": "pnpm run \"/^dev:(frontend|backend)$/\"",
|
|
74
|
+
"dev:frontend": "pnpm --filter @app/frontend dev",
|
|
75
|
+
"dev:backend": "pnpm --filter @app/backend dev",
|
|
76
|
+
"build": "pnpm -r build",
|
|
77
|
+
"build:frontend:live": "pnpm --filter @app/frontend build:live",
|
|
78
|
+
"start:backend": "pnpm --filter @app/backend start",
|
|
79
|
+
"deploy:frontend:live": "pnpm build:frontend:live && bash apps/frontend/deploy.sh live",
|
|
80
|
+
"db:migrate": "pnpm --filter @app/backend migrate",
|
|
81
|
+
"lint": "eslint apps packages --no-error-on-unmatched-pattern",
|
|
82
|
+
"typecheck": "pnpm -r typecheck",
|
|
83
|
+
"format:check": "prettier --check .",
|
|
84
|
+
"check": "pnpm lint && pnpm typecheck && pnpm format:check"
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## 6. 이름을 바꿀 때
|
|
89
|
+
|
|
90
|
+
**서버가 부르는 이름부터 찾는다.** 배포 스크립트 · pm2 · CI · Dockerfile 이 `pnpm <이름>` 을 부르면 이름을 바꾸는 커밋에 함께 담는다 —
|
|
91
|
+
안 그러면 다음 배포에서 서버가 안 뜬다. 그다음 README · `docs/` · `CLAUDE.md` · `.claude/settings.json` 의 허용 목록을 고친다.
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
grep -rnE "pnpm (run )?<옛 이름>" . --exclude-dir=node_modules --exclude-dir=.git
|
|
95
|
+
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# 작업 공간 · 의존성 · 환경 변수
|
|
2
|
+
|
|
3
|
+
> 언제 보나: 새 프로젝트를 만들 때, 앱 · 패키지 · 의존성 · 환경 변수를 더할 때.
|
|
4
|
+
|
|
5
|
+
## 1. 도구 — 고정한다
|
|
6
|
+
|
|
7
|
+
| 항목 | 규칙 |
|
|
8
|
+
| ---------------- | ---------------------------------------------------------------------------------------- |
|
|
9
|
+
| 패키지 매니저 | **pnpm 만.** npm · yarn lockfile 을 만들지 않는다. `packageManager` 필드에 버전을 적는다 |
|
|
10
|
+
| Node | 버전 하나로 고정 — `.nvmrc` 또는 `.node-version` + `engines.node` |
|
|
11
|
+
| lockfile | 커밋한다. CI · 서버는 `pnpm install --frozen-lockfile` |
|
|
12
|
+
| lint · 포맷 설정 | **루트가 갖는다.** 앱 · 패키지에 따로 두지 않는다 |
|
|
13
|
+
|
|
14
|
+
## 2. 폴더 — 실행 단위와 재사용 단위
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
apps/ 실행 단위 — 혼자 실행 · 빌드된다
|
|
18
|
+
packages/ 재사용 단위 — 둘 이상의 앱이 함께 쓰는 것
|
|
19
|
+
docs/ 개발 문서 (process/docs-structure.md)
|
|
20
|
+
scripts/ 배포 · 운영 스크립트
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- **앱끼리 서로 import 하지 않는다.** 함께 쓸 것은 `packages/` 로 뺀다
|
|
24
|
+
- **쓰는 곳이 둘 생길 때 패키지를 만든다.** 미리 만들지 않는다
|
|
25
|
+
- 앱 이름은 짧은 한 낱말(`web` · `admin` · `api` · `frontend` · `backend`). 스크립트 이름의 대상이 된다 ([scripts.md](scripts.md))
|
|
26
|
+
- 사용자 화면과 관리 화면은 앱을 나눈다 — 관리 코드 · 무거운 의존이 사용자 번들에 섞이지 않는다
|
|
27
|
+
|
|
28
|
+
## 3. 의존성
|
|
29
|
+
|
|
30
|
+
- **새 라이브러리를 들이면 고른 이유를 그 작업 문서에 적는다**
|
|
31
|
+
- 무거운 선택 기능(표 · 달력)은 쓰는 앱에만 설치한다
|
|
32
|
+
- 다른 저장소의 패키지는 **npm 버전**으로 쓴다. 함께 고칠 때만 `link:` 로 잠시 덮고, 커밋 전에 되돌린다
|
|
33
|
+
- `link:` 를 되돌릴 때 **선택 peer 의 버전을 다시 본다** — 링크된 쪽 `node_modules` 의 peer 를 쓰므로 틀린 버전이 가려진다
|
|
34
|
+
- 링크하는 동안 React 가 두 벌 되지 않게 `resolve.dedupe: ["react", "react-dom", "react-router-dom"]` (Vite)
|
|
35
|
+
|
|
36
|
+
## 4. 환경 변수
|
|
37
|
+
|
|
38
|
+
| 어디 | 규칙 |
|
|
39
|
+
| ---------- | --------------------------------------------------------------------------------------- |
|
|
40
|
+
| 프런트 | **`VITE_*` 는 브라우저에 그대로 실리는 공개 값이다.** 비밀 · 키 · DB 주소를 넣지 않는다 |
|
|
41
|
+
| 서버 | 비밀은 서버에만. 시작할 때 필수 값을 검사하고 **없으면 바로 멈춘다** |
|
|
42
|
+
| 파일 | `.env.example` 에 키 이름과 예시 값을 둔다(커밋). 실제 값 파일은 커밋하지 않는다 |
|
|
43
|
+
| 로그 · Git | 비밀값을 남기지 않는다 |
|
|
44
|
+
|
|
45
|
+
**환경 이름은 `local` · `dev` · `live` 셋.** 스크립트 변형(`build:frontend:live`) · Vite 모드 · `APP_ENV` 가 같은 낱말을 쓴다.
|
|
46
|
+
|
|
47
|
+
## 5. 데이터
|
|
48
|
+
|
|
49
|
+
- 운영 DB 변경은 migration 으로만. 되돌리는 방법을 같이 검토한다
|
|
50
|
+
- 개발용 더미 데이터를 운영에 넣지 않는다
|
|
51
|
+
- 외부 서비스(문자 · 결제 · 외부 API)는 승인 전까지 **합성(가짜) 구현**으로 개발한다. 실제 호출을 켜는 스위치는 명시적으로
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
<프로젝트 한 줄 소개>.
|
|
4
|
+
|
|
5
|
+
## 개발 기준
|
|
6
|
+
|
|
7
|
+
이 프로젝트는 **`@txstack/dev-guide`** 를 따른다. 규칙은 설치된 버전에 있다 —
|
|
8
|
+
`node_modules/@txstack/dev-guide/llms.txt` (목차), `rules/` (스크립트 · 커밋 · 작업 공간 · 코드), `process/` (문서 프로세스 · AI 와 일하는 법).
|
|
9
|
+
dev-guide 와 다르게 하는 것은 [docs/rules/00_DEV_GUIDE_DIFF.md](docs/rules/00_DEV_GUIDE_DIFF.md) 에만 적는다.
|
|
10
|
+
|
|
11
|
+
<!--
|
|
12
|
+
UI 를 @txstack/ui 로 짓는 프로젝트는 여기에 "UI 는 txstack 을 먼저 쓴다" 문단을 붙인다.
|
|
13
|
+
문단은 설치된 @txstack/ui 의 ai/rules.md 「소비자 프로젝트 시작 묶음」에 있다 — 그 판 그대로 복사한다.
|
|
14
|
+
dev-guide 는 프로젝트를 굴리는 규칙, 그 문단은 화면 부품을 고르는 규칙이다. 둘 다 둔다.
|
|
15
|
+
-->
|
|
16
|
+
|
|
17
|
+
## 시작하기
|
|
18
|
+
|
|
19
|
+
`CURRENT.md` → `docs/README.md` 순서로 읽는다. 지금 상태와 다음 할 일은 `CURRENT.md` 가 갖는다 — 이 문서에 상태를 쓰지 않는다.
|
|
20
|
+
|
|
21
|
+
## 이 프로젝트 고유의 것
|
|
22
|
+
|
|
23
|
+
- 앱: <apps/… — 역할>
|
|
24
|
+
- 도메인 규칙: <docs/rules/NN_… 링크>
|
|
25
|
+
- 배포: <docs/project/NN_… 링크>
|
|
26
|
+
|
|
27
|
+
## 검증 명령
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
pnpm check # lint + typecheck + format:check (+ test)
|
|
31
|
+
pnpm build
|
|
32
|
+
```
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# <프로젝트> 현재 상태
|
|
2
|
+
|
|
3
|
+
기준일: YYYY-MM-DD. 상태는 이 파일에만 쓴다. 최신이 위.
|
|
4
|
+
|
|
5
|
+
## 지금
|
|
6
|
+
|
|
7
|
+
<진행 중인 작업 번호와 단계 한두 줄. 배포 상태>
|
|
8
|
+
|
|
9
|
+
## 다음 할 일
|
|
10
|
+
|
|
11
|
+
1. <작업 nnn T2 — 링크>
|
|
12
|
+
2. <…>
|
|
13
|
+
|
|
14
|
+
## 남은 결정
|
|
15
|
+
|
|
16
|
+
- <무엇 — 누가>
|
|
17
|
+
|
|
18
|
+
## 명령
|
|
19
|
+
|
|
20
|
+
`pnpm dev` · `pnpm check` · `pnpm build` · <프로젝트 고유 명령>
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# 00. dev-guide 와 다른 점
|
|
2
|
+
|
|
3
|
+
> 언제 보나: dev-guide 의 규칙이 이 프로젝트에서 그대로인지 확인할 때.
|
|
4
|
+
|
|
5
|
+
따르는 판: `@txstack/dev-guide` <0.x.y>. **여기 없는 것은 dev-guide 그대로다.**
|
|
6
|
+
|
|
7
|
+
| dev-guide 규칙 | 이 프로젝트 | 이유 · 결정 |
|
|
8
|
+
| ----------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|
|
9
|
+
| <예: 커밋은 요청할 때만 (rules/commits.md 3장)> | <검사 · 빌드가 통과하면 AI 가 스스로 커밋 · 푸시> | <YYYY-MM-DD 사용자 결정 — 사용자는 검수를 맡는다> |
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# 개발 문서 색인
|
|
2
|
+
|
|
3
|
+
기준일: YYYY-MM-DD. 이 프로젝트는 [`@txstack/dev-guide`](../node_modules/@txstack/dev-guide/README.md) 를 따른다.
|
|
4
|
+
|
|
5
|
+
## 문서 구조
|
|
6
|
+
|
|
7
|
+
| 위치 | 역할 | 파일명 |
|
|
8
|
+
| --------------- | ------------------------------------ | -------------- |
|
|
9
|
+
| `project/` | 서비스 목적 · 화면 · 데이터 · 로드맵 | `NN_TITLE.md` |
|
|
10
|
+
| `rules/` | 이 프로젝트 고유의 규약 | `NN_TITLE.md` |
|
|
11
|
+
| `requirements/` | 무엇을 왜 만드나 · 수용 기준 | `nnn_title.md` |
|
|
12
|
+
| `plans/` | 어떻게 만드나 · 체크리스트 | `nnn_title.md` |
|
|
13
|
+
| `verification/` | 증거 · QA · 인계 | `nnn_title.md` |
|
|
14
|
+
| `reports/` | 밖에 건네는 문서 | `nnn_title.md` |
|
|
15
|
+
|
|
16
|
+
한 작업은 같은 번호를 쓴다. 요구사항 → 계획 → 구현 → 검증 → 보고.
|
|
17
|
+
|
|
18
|
+
## 읽는 순서
|
|
19
|
+
|
|
20
|
+
- [프로젝트 개요](project/01_PROJECT_OVERVIEW.md)
|
|
21
|
+
- [dev-guide 와 다른 점](rules/00_DEV_GUIDE_DIFF.md)
|
|
22
|
+
|
|
23
|
+
## 작업
|
|
24
|
+
|
|
25
|
+
### nnn — <제목>
|
|
26
|
+
|
|
27
|
+
[요구사항](requirements/nnn_title.md) → [계획](plans/nnn_title.md) → [검증](verification/nnn_title.md)
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# nnn. <제목> — 계획
|
|
2
|
+
|
|
3
|
+
기준일: YYYY-MM-DD. 상태: <합의 전 | 합의됨 | 진행 중 | 완료>.
|
|
4
|
+
|
|
5
|
+
[요구사항](../requirements/nnn_title.md) · [검증](../verification/nnn_title.md)
|
|
6
|
+
|
|
7
|
+
## 1. 관찰 — 지금 코드는
|
|
8
|
+
|
|
9
|
+
<읽은 코드 · 문서 · 실행 결과. 요구사항의 전제와 다른 것이 있으면 여기서 멈추고 알린다>
|
|
10
|
+
|
|
11
|
+
## 2. 변경 범위
|
|
12
|
+
|
|
13
|
+
| 어디 | 무엇을 | AC |
|
|
14
|
+
| ---- | ------ | ---- |
|
|
15
|
+
| <…> | <…> | AC01 |
|
|
16
|
+
|
|
17
|
+
## 3. 순서
|
|
18
|
+
|
|
19
|
+
### T1. <단계 이름> — AC01
|
|
20
|
+
|
|
21
|
+
<무엇을 · 어떻게. 되돌리기 어려운 것(공개 API · 화면 모양 · DB)은 예제로 먼저 합의한다>
|
|
22
|
+
|
|
23
|
+
### T2. <단계 이름> — AC02
|
|
24
|
+
|
|
25
|
+
<…>
|
|
26
|
+
|
|
27
|
+
## 4. 정할 것
|
|
28
|
+
|
|
29
|
+
1. **<질문>** — 추천: <안>. 이유: <…>
|
|
30
|
+
|
|
31
|
+
## 5. 검증 방법
|
|
32
|
+
|
|
33
|
+
- 명령: `pnpm check` · `pnpm build` · <…>
|
|
34
|
+
- 화면: <무엇을 어디서 본다>
|
|
35
|
+
- AC 별 증거: <…>
|
|
36
|
+
|
|
37
|
+
## 6. 체크리스트
|
|
38
|
+
|
|
39
|
+
- [ ] T1
|
|
40
|
+
- [ ] T2
|
|
41
|
+
- [ ] 검증 문서 · 인계
|
|
42
|
+
- [ ] `CURRENT.md` · `docs/README.md`
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# nnn. <제목> — <요약 보고 | 회의 안건 | 협의안>
|
|
2
|
+
|
|
3
|
+
> 읽는 사람: <운영진 · ○○ 부서 · 외부 담당자>. 기준일: YYYY-MM-DD.
|
|
4
|
+
|
|
5
|
+
## 한 줄 요약
|
|
6
|
+
|
|
7
|
+
<결론부터. 쉬운 말로>
|
|
8
|
+
|
|
9
|
+
## 한 것
|
|
10
|
+
|
|
11
|
+
- <…>
|
|
12
|
+
|
|
13
|
+
## 하지 않은 것 · 이유
|
|
14
|
+
|
|
15
|
+
- <…>
|
|
16
|
+
|
|
17
|
+
## 결정이 필요한 것
|
|
18
|
+
|
|
19
|
+
| 무엇 | 언제까지 | 추천 |
|
|
20
|
+
| ---- | -------- | ---- |
|
|
21
|
+
| <…> | <…> | <…> |
|
|
22
|
+
|
|
23
|
+
## 다음
|
|
24
|
+
|
|
25
|
+
<…>
|
|
26
|
+
|
|
27
|
+
<!-- 증거 · 개발 인계 · 계산 규칙은 옮겨 적지 않고 링크한다. 커밋 번호 · 파일 경로는 꼭 필요할 때만 -->
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# nnn. <제목> — 요구사항
|
|
2
|
+
|
|
3
|
+
기준일: YYYY-MM-DD. 상태: <합의 전 | 합의됨 (YYYY-MM-DD) | 일부 구현 | 완료>.
|
|
4
|
+
|
|
5
|
+
[계획](../plans/nnn_title.md) · [검증](../verification/nnn_title.md)
|
|
6
|
+
|
|
7
|
+
## 배경
|
|
8
|
+
|
|
9
|
+
<무엇이 문제이고 왜 지금 하나. 요청 · 회의 · 결함 보고의 출처를 링크한다>
|
|
10
|
+
|
|
11
|
+
## 범위
|
|
12
|
+
|
|
13
|
+
- 한다: <…>
|
|
14
|
+
- 하지 않는다: <…> — <왜>
|
|
15
|
+
|
|
16
|
+
## 수용 기준
|
|
17
|
+
|
|
18
|
+
확인할 수 있는 문장으로 쓴다. 계획 · 검증이 같은 ID 를 쓴다.
|
|
19
|
+
|
|
20
|
+
| ID | 완료 판정 기준 |
|
|
21
|
+
| ---- | -------------- |
|
|
22
|
+
| AC01 | <…> |
|
|
23
|
+
| AC02 | <…> |
|
|
24
|
+
|
|
25
|
+
## 결정 · 미정
|
|
26
|
+
|
|
27
|
+
| 항목 | 상태 | 내용 |
|
|
28
|
+
| ---- | ----------------------------- | ---- |
|
|
29
|
+
| <…> | 확정 (YYYY-MM-DD 사용자 결정) | <…> |
|
|
30
|
+
| <…> | 미정 — <누가 언제까지> | <…> |
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# nnn. <제목> — 검증 · 인계
|
|
2
|
+
|
|
3
|
+
기준일: YYYY-MM-DD.
|
|
4
|
+
|
|
5
|
+
[요구사항](../requirements/nnn_title.md) · [계획](../plans/nnn_title.md)
|
|
6
|
+
|
|
7
|
+
## 결과 요약
|
|
8
|
+
|
|
9
|
+
| AC | 결과 | 증거 |
|
|
10
|
+
| ---- | ------------------------ | -------------- |
|
|
11
|
+
| AC01 | 통과 · 실패 · **미실행** | <아래 절 링크> |
|
|
12
|
+
|
|
13
|
+
## T1. <단계 이름> — YYYY-MM-DD
|
|
14
|
+
|
|
15
|
+
### 구현
|
|
16
|
+
|
|
17
|
+
<무엇을 바꿨나 — 파일 · 커밋>
|
|
18
|
+
|
|
19
|
+
### 증거
|
|
20
|
+
|
|
21
|
+
<실행한 명령과 결과, 화면 캡처. 실행하지 않은 것은 "미실행" 과 이유>
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
$ pnpm check
|
|
25
|
+
<결과>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 사용자 확인 체크리스트 (QA)
|
|
29
|
+
|
|
30
|
+
사람이 직접 봐야 하는 것.
|
|
31
|
+
|
|
32
|
+
- [ ] <어디서> <무엇을 하면> <무엇이 보여야 한다>
|
|
33
|
+
|
|
34
|
+
## 인계
|
|
35
|
+
|
|
36
|
+
- **바뀐 것**: <…>
|
|
37
|
+
- **남은 것**: <…>
|
|
38
|
+
- **남은 결정**: <…>
|
|
39
|
+
- **배포**: <안 함 | dev 배포 YYYY-MM-DD | live …>
|
|
40
|
+
- **다음 작업**: <…>
|