feat: 가상화 문서들 추가
This commit is contained in:
DongHyeonka
@@ -0,0 +1,254 @@
|
||||
# 단계 계약
|
||||
|
||||
단계마다 넷을 정한다 — **입력 · 스킬 · 관문 · 산출물.** 원장에 적히는 것도 이 넷이다.
|
||||
|
||||
관문은 종료 코드가 0 이어야 지난 것이다. 0 이 아니면 그 단계는 `FAILED` 이고 다음 단계로
|
||||
넘어가지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## S1 — 코드베이스 → SSOT
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `analyzing-codebase-for-tech-log` |
|
||||
| 입력 | 분석 대상 저장소 경로(사용자가 준다) · 그 저장소의 `AGENTS.md`(있으면) |
|
||||
| 산출물 | `docs/<프로젝트>/final/document.md` |
|
||||
| 관문 | `python3 scripts/verify-project-layout.py <프로젝트>` |
|
||||
|
||||
**분석 대상 저장소는 이 저장소 밖이다.** `docs/<프로젝트>` 는 이 저장소 기준이고, 분석 대상은
|
||||
사용자가 준 절대 경로다. 두 저장소를 섞지 않는다 — 대상 저장소를 고치지 않는다.
|
||||
|
||||
**`analysis-queue.yaml` 은 여러 프로젝트를 줄 세울 때만 쓴다.** 사용자가 저장소 하나를
|
||||
지목했으면 큐 없이 그 하나를 분석한다. 큐가 있으면 큐가 정한 활성 프로젝트를 따른다.
|
||||
|
||||
작업 재료(`analysis/` · `notes/` · `checkpoints/` · `state.json` · `source-index.md`)는 분석
|
||||
중에만 있고, 끝나면 `final/document.md` 로 합치고 지운다.
|
||||
|
||||
```bash
|
||||
python3 scripts/fold-analysis-into-final.py <프로젝트>
|
||||
```
|
||||
|
||||
**S2 가 무엇을 기대하는지 알고 쓴다.** S2 는 `final/document.md` 를 절 단위로 훑어 후보를
|
||||
찾는다. 절 제목이 무엇을 다루는지 말하지 않으면 후보가 안 잡힌다. 접어 넣은 문서라면
|
||||
제1부(통합 분석)가 후보 범위이고 제2·3부는 근거다.
|
||||
|
||||
산출물이 이미 있고 이 글감의 근거가 그 안에 있으면 `SKIPPED` 로 적고 사유를 남긴다.
|
||||
|
||||
### 이미 접어 넣은 프로젝트를 다시 볼 때 — 대조 모드
|
||||
|
||||
`final/document.md` 가 이미 있는 프로젝트에 S1 을 다시 돌리는 것은 **분석이 아니라 대조**다.
|
||||
스킬의 절차(작업 재료를 만들고 → 분석하고 → 접어 넣는다)를 그대로 밟으면 두 곳이 깨진다.
|
||||
|
||||
- `docs/<프로젝트>/` 에 `state.json`·`analysis/` 를 만들면 배치 검사기가 error 로 센다.
|
||||
완료된 프로젝트의 폴더는 `final/` 과 `tech-log-studio/` 뿐이다.
|
||||
- `final/document.md` 를 고치면 `ssotSha256` 이 어긋나 분해 계약이 통째로 무효가 된다.
|
||||
|
||||
그래서 대조 모드는 이렇게 돈다.
|
||||
|
||||
| | 분석 모드 | 대조 모드 |
|
||||
|---|---|---|
|
||||
| 작업 재료 | `docs/<프로젝트>/analysis/` | `runs/<프로젝트>/<runId>/stage/S1/` |
|
||||
| SSOT | 만들거나 접어 넣는다 | **고치지 않는다.** 보강 후보만 적는다 |
|
||||
| 끝 조건 | fold 하고 재료를 지운다 | 어긋난 것·빠진 것을 목록으로 남긴다 |
|
||||
|
||||
SSOT 가 코드와 **어긋나는** 것을 찾으면 그것은 보강 후보가 아니다. 크게 적고 사람에게
|
||||
올린다 — 이미 그 SSOT 를 근거로 쓴 기록이 있기 때문이다.
|
||||
|
||||
---
|
||||
|
||||
## S2 — SSOT → 분해 계약
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `deriving-tech-log-root-tree` |
|
||||
| 입력 | `docs/<프로젝트>/final/document.md` **하나** |
|
||||
| 산출물 | `docs/<프로젝트>/tech-log-studio/tech-log-tree.json` |
|
||||
| 관문 | `python3 scripts/build-tech-log-tree.py <프로젝트>` → `python3 scripts/verify-tech-log-tree.py <프로젝트>` (error 0) |
|
||||
|
||||
`analysis/**` 를 후보를 찾으려고 열지 않는다. 분석에만 있는 자료를 발견하면 `final/document.md`
|
||||
를 먼저 보강한다.
|
||||
|
||||
**검사기나 계약이 요구하는데 스킬의 절차가 안 적는 칸이 있다.** 손으로 채운다.
|
||||
|
||||
| 칸 | 무엇 |
|
||||
|---|---|
|
||||
| `candidateScope` | 후보를 찾은 범위. 적지 않으면 모듈 분석 절 제목이 전부 글감이 된다 |
|
||||
| `sourceRepository` | 분석한 저장소의 경로·리비전·그렇게 판단한 근거. 모르면 `null`, 지어내지 않는다 |
|
||||
| `ssotSha256` | `build-tech-log-tree.py` 가 채운다. 그래서 build 를 먼저 돌리고 verify 를 돌린다 |
|
||||
| `ssot-assets` · `ssot-evidence` | SSOT 가 이미 그린 그림과 이미 돌린 측정을 글감에 배정한다. 계약 문서에만 있고 절차에는 이 단계가 없다 |
|
||||
| `candidateScope.excludedAnchorPattern` | 「범위 밖 글감」 검사가 이 칸으로 판정한다. 없으면 그 검사가 통째로 꺼진다 |
|
||||
|
||||
`assetLedger` 는 계약이 요구하지만 스크립트 어느 것도 읽지 않는다. 사람이 보는 칸이다.
|
||||
|
||||
**`source` 앵커의 형식이 어디에도 적혀 있지 않다.** keycloak 은 「h2 슬러그 + `-ap1`」 같은
|
||||
합성 앵커를 쓰고, 제목 슬러그를 쓴 프로젝트도 있다. 검사기는 SSOT 경로를 포함하는지만 보고
|
||||
실재하는 heading 으로 풀지 않는다. **한 프로젝트 안에서는 한 형식으로 통일한다** — S4 가
|
||||
`--heading` 값을 이 앵커에서 옮기기 때문이다.
|
||||
|
||||
**검사기는 「후보 ↔ 글감」만 본다. 「SSOT ↔ 후보」는 안 본다.** 그래서 SSOT 에 있는 재료를
|
||||
후보 대장에 올리지도 않고 지나쳐도 error 가 0 이다. 범위의 절을 끝까지 읽는 것은 사람의 일이다.
|
||||
|
||||
제외가 0 건인 분해는 선별하지 않은 분해다. 후보마다 처분(`PROMOTE`·`MERGE_INTO`·
|
||||
`KEEP_IN_SSOT`·`NEEDS_EVIDENCE`·`NEEDS_DECISION`)을 적고, 사람이 다시 읽은 것만
|
||||
`dispositionReview: CONFIRMED` 로 둔다.
|
||||
|
||||
---
|
||||
|
||||
## S3 — 글감 → 기록
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `writing-tech-log-records` |
|
||||
| 입력 | `tech-log-tree.json` 의 노드 하나 · 그 노드의 `source` 앵커가 가리키는 SSOT 절 |
|
||||
| 산출물 | `docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<기록>.md` |
|
||||
| 관문 | 아래 셋 |
|
||||
|
||||
```bash
|
||||
python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
|
||||
node --experimental-transform-types \
|
||||
.agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
|
||||
node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
|
||||
node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
|
||||
```
|
||||
|
||||
**노드가 `PROMOTE` 이고 `CONFIRMED` 인지 먼저 본다.** 아니면 쓰지 않는다.
|
||||
|
||||
**인용한 줄은 SSOT 에서 찾아 대조한다.** 앞선 기록에서 옮겨 적은 것은 확인한 것이 아니다 —
|
||||
그렇게 게시된 기록에 SSOT 와 다른 redirect URI 가 네 곳 있었다.
|
||||
|
||||
그림이 필요해 보이면 **`final/assets/` 에 이미 있는지부터 본다.** 계약의 `ssot-assets` 가 이
|
||||
글감에 배정한 그림이 있으면 그 파일을 그대로 가리킨다. 없을 때만 S4 로 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
## S4 — 기록 → 그림
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `technical-visualizer` |
|
||||
| 입력 | S3 이 쓴 기록 `.md`(무엇을 그릴지) · 그 기록의 `source` 앵커가 가리키는 SSOT 절(그림의 사실) |
|
||||
| 산출물 | `final/.techviz/<이름>/{context.json,prompt.md,spec.json}` · `final/assets/<이름>/` |
|
||||
| 관문 | `techviz lint` · `check-figure-text.py` · `check-figure-overlap.py` · `preview-figure.py` 로 눈 확인 |
|
||||
|
||||
**입력이 둘이라는 것이 이 단계의 전부다.**
|
||||
|
||||
- **무엇을 그릴지는 기록 본문이 정한다.** 세 관문(자리가 Case·Concept 인가 · 표가 아닌가 ·
|
||||
옆 문단이 이미 말하지 않았는가)을 지나야 그린다. 그리고 **그림이 주장하는 것을 기록 본문이
|
||||
말해야 한다.** 본문이 안 적은 단계를 그림만 넣으면 설명 없는 주장이 남는다. 순서는
|
||||
본문을 먼저 보강하고 그다음 그림을 붙인다.
|
||||
- **그림의 사실은 SSOT 절이 댄다.** 기록은 SSOT 의 인용이라 줄 번호가 근거가 되지 못한다.
|
||||
`techviz prepare` 에는 `final/document.md` 를 넣고, 절은 기록의 `source` 앵커로 지목한다.
|
||||
|
||||
```bash
|
||||
./scripts/techviz prepare docs/<프로젝트>/final/document.md \
|
||||
--heading "<기록의 source 앵커가 가리키는 절 제목>" \
|
||||
-o docs/<프로젝트>/final/.techviz/<이름>/context.json
|
||||
```
|
||||
|
||||
`--line` 은 쓰지 않는다. context 는 관리 블록을 접은 좌표를 쓰므로 파일 줄 번호와 어긋난다.
|
||||
|
||||
**그림 안에는 이름만 넣는다.** 문장은 `<desc>` 와 옆 문단에 둔다. lint 는 이것을 못 잡는다 —
|
||||
`check-figure-text.py` 가 잡는다.
|
||||
|
||||
**lint 는 좌표를 안 본다.** 관계가 이어져 있는지만 본다. 그래서 구역 둘이 겹쳐 그려지거나
|
||||
라벨이 상자에 먹혀도 통과한다. `check-figure-overlap.py` 가 그것을 본다.
|
||||
|
||||
```bash
|
||||
python3 scripts/check-figure-overlap.py <프로젝트>
|
||||
python3 scripts/check-figure-overlap.py --file 그림.svg
|
||||
```
|
||||
|
||||
**그래도 마지막에는 눈으로 본다.** 검사기가 보는 것은 배경 사각형의 좌표라, 글자가 상자
|
||||
밖으로 조금 나가거나 화살표가 라벨을 지나는 것은 못 잡는다.
|
||||
|
||||
기록에 되적는다 — frontmatter `assets:` 에 `key` 와 `file`(=`final/assets/<이름>/<이름>.svg`)
|
||||
을 적고, 본문에는 마크다운 이미지로 넣는다. `:::evidence` 는 저장소에 쓰지 않는다. 사본을
|
||||
`tech-log-studio/` 쪽에 두지 않는다 — 사본에는 `.techviz/<이름>/` 이 없어 다시 못 만든다.
|
||||
|
||||
---
|
||||
|
||||
## S5 — AI 티 제거
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `rewriting-technical-prose-naturally` |
|
||||
| 입력 | S3·S4 를 지난 기록 `.md` (제자리 수정) |
|
||||
| 산출물 | 같은 파일 |
|
||||
| 관문 | `check_prose.mjs` error 0 · `style_profile.mjs` · S3 관문 재실행 |
|
||||
|
||||
```bash
|
||||
S=.agents/skills/rewriting-technical-prose-naturally/scripts
|
||||
node $S/check_prose.mjs --warn <기록.md> # error 0 까지 고친다
|
||||
node $S/style_profile.mjs <기록.md>
|
||||
```
|
||||
|
||||
문서 전체를 다시 쓴 것이 아니면 `--doc` 을 빼고 부른다.
|
||||
|
||||
**`density.mjs` 는 본문이 있는 종류에만 건다.** 그 기준은 글 한 편(낱말 1277+ · 코드블록 1+ ·
|
||||
수치 13+)을 잰 값이고, Reference·Question·Decision 은 칸이 평문이라 코드블록을 넣는 것 자체가
|
||||
규칙 위반이다. 본문 없는 종류에 걸면 구조적으로 통과할 수 없는 관문이 되고, 통과시키려면
|
||||
없는 측정값을 지어내야 한다.
|
||||
|
||||
**문체 수치를 맞추려고 문장을 넣지 않는다.** 검사기는 표면 패턴만 보고 뜻은 못 본다.
|
||||
|
||||
**보호 구간을 건드리지 않는다** — 수치·날짜·버전·단위·코드·명령어·URL·직접 인용·공식 명칭은
|
||||
원문과 한 글자도 달라지면 안 된다. 그래서 문장을 고친 뒤 `check_evidence.mjs` 를 다시 돌린다.
|
||||
|
||||
---
|
||||
|
||||
## S6 — 일한 사람의 목소리
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `writing-as-the-person-who-did-it` |
|
||||
| 입력 | S5 를 지난 기록 `.md` · **그리고 그 기록의 상류 자료** (SSOT · 커밋 메시지 · 주석 · `확인하지 못한 것` 칸) |
|
||||
| 산출물 | 같은 파일 |
|
||||
| 관문 | `check_voice.mjs` · `check_prose.mjs` 재실행 · S3 관문 재실행 |
|
||||
|
||||
```bash
|
||||
node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
|
||||
node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
|
||||
```
|
||||
|
||||
**S5 다음이다.** 번역투와 반복 문형을 걷어낸 뒤라야 채울 자리가 보인다. 그리고 이 스킬이
|
||||
넣은 문장을 `check_prose` 가 다시 본다 — 그래서 재실행이 관문이다.
|
||||
|
||||
**자료에 흔적이 없으면 이 단계는 여기서 끝난다.** 없는 사람을 만들지 않는다. 「처음에는」·
|
||||
「고민 끝에」·「놀랍게도」를 자료 없이 쓰면 지어낸 것이다. 원장에는 `DONE` 에 「흔적 없음」을
|
||||
적는다 — `SKIPPED` 가 아니다. 찾아봤다는 것이 이 단계의 일이다.
|
||||
|
||||
**`check_voice.mjs` 는 목소리가 모자란지 재지 않는다.** 지어낸 목소리를 잡는다. 조용하다고
|
||||
목소리가 생긴 것은 아니다.
|
||||
|
||||
---
|
||||
|
||||
## S7 — Studio 저장
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 스킬 | `publishing-tech-log-to-studio` |
|
||||
| 입력 | S6 을 지난 기록 `.md` · frontmatter `assets:` 가 가리키는 SVG |
|
||||
| 산출물 | Studio 작업본. 기록 frontmatter 의 `id`·`studio:` |
|
||||
| 관문 | 상태 레일이 `저장됨` · `python3 scripts/build-tech-log-tree.py` → `verify-tech-log-tree.py` |
|
||||
|
||||
**저장까지다. 게시하지 않는다.**
|
||||
|
||||
Asset 을 본문보다 먼저 올린다. 순서를 뒤집으면 미리보기가 본문 전체를 막는다.
|
||||
|
||||
바뀐 것이 없으면 저장 버튼을 누르지 않는다 — 누를 때마다 `version` 이 올라가고 앞서 만든
|
||||
검증·미리보기 산출물이 무효가 된다.
|
||||
|
||||
---
|
||||
|
||||
## 관문 요약
|
||||
|
||||
| 단계 | 명령 |
|
||||
|---|---|
|
||||
| S1 | `verify-project-layout.py <프로젝트>` |
|
||||
| S2 | `build-tech-log-tree.py` → `verify-tech-log-tree.py` (error 0) |
|
||||
| S3 | `studio-body.py` → `check_body.mjs` · `check_prose.mjs` · `check_evidence.mjs --repo` |
|
||||
| S4 | `techviz lint` · `check-figure-text.py` · `check-figure-overlap.py` · `preview-figure.py` (눈 확인) |
|
||||
| S5 | `check_prose.mjs` (error 0) · `style_profile.mjs` · S3 관문 |
|
||||
| S6 | `check_voice.mjs` · `check_prose.mjs` · S3 관문 |
|
||||
| S7 | `저장됨` 확인 · `build-tech-log-tree.py` → `verify-tech-log-tree.py` |
|
||||
@@ -0,0 +1,275 @@
|
||||
# 서브에이전트 프롬프트
|
||||
|
||||
단계마다 에이전트를 하나 띄운다. 아래를 그대로 쓰고 `<...>` 만 바꾼다.
|
||||
|
||||
## 모든 프롬프트에 들어가는 넷
|
||||
|
||||
1. **스킬 이름과 「SKILL.md 를 끝까지 먼저 읽어라」.** 요약을 주지 않는다. 요약을 주면
|
||||
스킬을 안 연다.
|
||||
2. **자기 단계의 입력 경로만.** 앞 단계가 무엇을 했는지 설명하지 않는다.
|
||||
3. **관문 명령 원문.** 「검사해라」가 아니라 붙여 넣을 수 있는 명령을 준다.
|
||||
4. **스킬 영수증** — SKILL.md 에서 한 줄을 **원문 그대로** 인용해 돌려보내게 한다.
|
||||
`verify-pipeline-run.py` 가 그 문자열이 실제 파일 안에 있는지 대조한다.
|
||||
|
||||
## 돌려받는 형식 (모든 단계 공통)
|
||||
|
||||
```json
|
||||
{
|
||||
"stage": "S3",
|
||||
"skill": "writing-tech-log-records",
|
||||
"skillEcho": "<SKILL.md 에서 그대로 옮긴 한 줄>",
|
||||
"status": "DONE",
|
||||
"outputs": ["docs/keycloak/tech-log-studio/.../case-x.md"],
|
||||
"gates": [{"cmd": "node ... check_body.mjs /tmp/studio-body.md", "exit": 0}],
|
||||
"notes": "<판단한 것과 못 한 것>"
|
||||
}
|
||||
```
|
||||
|
||||
`skillEcho` 를 지어내지 말라고 프롬프트에 적는다. 파일에 없는 문장이면 검사기가 잡는다.
|
||||
|
||||
## 파일을 쓰라고 할 때는 방법을 함께 준다
|
||||
|
||||
서브에이전트의 `Write` 는 「보고는 파일이 아니라 글로 돌려라」는 기본 정책에 막힐 수 있다.
|
||||
S1 처럼 산출물이 `.md` 인 단계는 그래서 한 줄을 더한다.
|
||||
|
||||
```
|
||||
파일을 쓸 때 Write 툴이 막히면 Bash heredoc (`cat > 경로 <<'EOF'`) 을 써라.
|
||||
```
|
||||
|
||||
이것을 안 적으면 에이전트가 산출물을 만들지 못하고 본문에 통째로 붙여 돌려준다.
|
||||
|
||||
---
|
||||
|
||||
## S1 — 코드베이스 → SSOT
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 1단계를 맡는다.
|
||||
|
||||
먼저 .agents/skills/analyzing-codebase-for-tech-log/SKILL.md 를 끝까지 읽어라.
|
||||
references/ 아래 문서도 그 스킬이 읽으라는 것을 읽어라. 요약본은 주지 않는다.
|
||||
|
||||
대상 저장소: <절대 경로>
|
||||
쓸 곳: docs/<프로젝트>/
|
||||
|
||||
analysis-queue.yaml 이 없으면 이 저장소 하나만 분석한다. 큐가 없다는 이유로 멈추지 마라.
|
||||
대상 저장소를 고치지 마라. 읽기만 한다.
|
||||
|
||||
끝나면 분석 재료를 SSOT 로 합쳐라:
|
||||
python3 scripts/fold-analysis-into-final.py <프로젝트>
|
||||
합친 뒤 analysis/ · notes/ · checkpoints/ · state.json · source-index.md 를 지운다.
|
||||
|
||||
관문:
|
||||
python3 scripts/verify-project-layout.py <프로젝트>
|
||||
error 0 이 될 때까지 고쳐라.
|
||||
|
||||
돌려줄 것 (JSON):
|
||||
stage, skill, skillEcho, status, outputs, gates, notes
|
||||
skillEcho 는 방금 읽은 SKILL.md 에서 네 작업에 해당하는 규칙 한 줄을 원문 그대로 옮긴 것이다.
|
||||
지어내지 마라 — 파일에 그 문자열이 있는지 기계가 대조한다.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## S2 — SSOT → 분해 계약
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 2단계를 맡는다.
|
||||
|
||||
먼저 .agents/skills/deriving-tech-log-root-tree/SKILL.md 를 끝까지 읽어라.
|
||||
references/candidate-disposition.md 와 references/decomposition-checklist.md 도 읽어라.
|
||||
출력 계약은 .agents/skills/writing-tech-log-records/references/tech-log-tree-contract.md 다.
|
||||
|
||||
입력: docs/<프로젝트>/final/document.md — 이것 하나다.
|
||||
analysis/** 를 후보를 찾으려고 열지 마라.
|
||||
|
||||
출력: docs/<프로젝트>/tech-log-studio/tech-log-tree.json
|
||||
|
||||
검사기가 error 로 요구하는데 스킬 본문이 안 적는 칸 셋을 손으로 채워라:
|
||||
candidateScope — 후보를 찾은 범위
|
||||
sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 모르면 null 로 두고 지어내지 마라
|
||||
ssotSha256 — build 가 채운다. 그래서 build 를 먼저 돌린다
|
||||
|
||||
제외가 0 건인 분해는 선별하지 않은 분해다. 후보마다 처분을 적고, 다시 읽은 것만
|
||||
dispositionReview: CONFIRMED 로 둬라.
|
||||
|
||||
관문:
|
||||
python3 scripts/build-tech-log-tree.py <프로젝트>
|
||||
python3 scripts/verify-tech-log-tree.py <프로젝트>
|
||||
error 0 까지 고쳐라.
|
||||
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## S3 — 글감 → 기록
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 3단계를 맡는다.
|
||||
|
||||
먼저 .agents/skills/writing-tech-log-records/SKILL.md 를 끝까지 읽어라.
|
||||
그 스킬이 가리키는 references/ 중 네 종류에 해당하는 것을 읽어라 —
|
||||
record-kinds.md · writing-each-kind.md · body-syntax.md · code-tables-diagrams.md ·
|
||||
explaining.md · ai-tells.md · choosing-a-diagram.md.
|
||||
|
||||
글감: docs/<프로젝트>/tech-log-studio/tech-log-tree.json 의 <주제> / <종류> / "<제목>"
|
||||
그 노드가 PROMOTE 이고 dispositionReview 가 CONFIRMED 인지 먼저 확인해라. 아니면 쓰지 마라.
|
||||
|
||||
근거: 그 노드의 source 앵커가 가리키는 docs/<프로젝트>/final/document.md 의 절.
|
||||
인용하는 줄은 SSOT 에서 찾아 대조해라. 기억이나 다른 기록에서 옮겨 적지 마라.
|
||||
|
||||
쓸 곳: docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<파일>.md
|
||||
|
||||
그림이 필요해 보이면 docs/<프로젝트>/final/assets/ 에 이미 있는지부터 봐라.
|
||||
없으면 이 단계에서 만들지 말고 notes 에 "그림 필요: <무엇을>" 이라고 적어라. 4단계가 만든다.
|
||||
|
||||
관문:
|
||||
python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
|
||||
node --experimental-transform-types \
|
||||
.agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
|
||||
node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
|
||||
node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
|
||||
error 0 까지 고쳐라.
|
||||
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## S4 — 기록 → 그림
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 4단계를 맡는다.
|
||||
|
||||
먼저 두 개를 읽어라:
|
||||
.agents/skills/technical-visualizer/SKILL.md — 끝까지
|
||||
.agents/skills/writing-tech-log-records/references/choosing-a-diagram.md
|
||||
|
||||
기록: <기록.md>
|
||||
이 기록을 읽고 무엇을 그릴지 정해라. 세 관문을 지나야 그린다 —
|
||||
자리가 Case·Concept 인가 / 표로 될 것이 아닌가 / 옆 문단이 이미 말하지 않았는가.
|
||||
그리고 그림이 주장하는 것을 이 기록 본문이 말하고 있어야 한다. 본문이 안 적은 단계를
|
||||
그림만으로 넣지 마라.
|
||||
|
||||
그림의 근거는 기록이 아니라 기록의 source 앵커가 가리키는 SSOT 절이다:
|
||||
./scripts/techviz prepare docs/<프로젝트>/final/document.md \
|
||||
--heading "<그 절 제목>" \
|
||||
-o docs/<프로젝트>/final/.techviz/<이름>/context.json
|
||||
--line 은 쓰지 마라.
|
||||
|
||||
그림 안의 <text> 는 전부 이름이어야 한다. 문장은 <desc> 와 옆 문단에 둬라.
|
||||
|
||||
관문:
|
||||
./scripts/techviz lint docs/<프로젝트>/final/.techviz/<이름>/spec.json \
|
||||
--context docs/<프로젝트>/final/.techviz/<이름>/context.json
|
||||
python3 scripts/check-figure-text.py <프로젝트>
|
||||
python3 scripts/check-figure-overlap.py <프로젝트>
|
||||
python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs
|
||||
마지막 것은 PNG 로 떠서 라벨이 상자를 덮지 않는지 눈으로 봐라. lint 는 그것을 못 잡는다.
|
||||
|
||||
기록에 되적어라 — frontmatter assets: 에 key 와 file, 본문에는 마크다운 이미지.
|
||||
:::evidence 를 저장소 .md 에 쓰지 마라.
|
||||
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함. 그리지 않기로 했으면 status 를 SKIPPED 로 하고
|
||||
어느 관문에 걸렸는지 적어라.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## S5 — AI 티 제거
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 5단계를 맡는다.
|
||||
|
||||
먼저 .agents/skills/rewriting-technical-prose-naturally/SKILL.md 를 끝까지 읽어라.
|
||||
그 스킬이 "첫 rewrite 전에 읽으라"고 지정한 references 세 개도 읽어라 —
|
||||
document-skeleton.md · article-shape.md · korean-tech-blog-register.md.
|
||||
|
||||
고칠 파일: <기록.md> (제자리에서 고친다)
|
||||
|
||||
너의 일은 문체다. 사실을 만들지 마라. 분류가 틀렸거나 근거가 모자란 것은 네 일이 아니다 —
|
||||
발견하면 고치지 말고 notes 에 적어라.
|
||||
|
||||
보호 구간을 건드리지 마라: 수치 · 날짜 · 버전 · 단위 · 코드 · 명령어 · URL · 직접 인용 ·
|
||||
공식 명칭. 한 글자도 달라지면 안 된다.
|
||||
|
||||
관문:
|
||||
S=.agents/skills/rewriting-technical-prose-naturally/scripts
|
||||
node $S/check_prose.mjs --warn <기록.md> # error 0 까지
|
||||
node $S/style_profile.mjs <기록.md>
|
||||
그리고 문장을 고쳤으니 본문 문법과 인용을 다시 본다:
|
||||
python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
|
||||
node --experimental-transform-types \
|
||||
.agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
|
||||
node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
|
||||
|
||||
수치를 맞추려고 문장을 넣지 마라. 검사기는 표면 패턴만 본다.
|
||||
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## S6 — 일한 사람의 목소리
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 6단계를 맡는다.
|
||||
|
||||
먼저 .agents/skills/writing-as-the-person-who-did-it/SKILL.md 를 끝까지 읽어라.
|
||||
references/voice-moves.md 도 읽어라. 그 스킬이 "이것보다 먼저 본다"고 한
|
||||
../rewriting-technical-prose-naturally/references/article-shape.md 를 먼저 읽어라.
|
||||
|
||||
고칠 파일: <기록.md> (제자리에서 고친다)
|
||||
상류 자료: docs/<프로젝트>/final/document.md · <대상 저장소의 커밋 메시지·주석·README>
|
||||
|
||||
찾을 것은 자료에 남아 있는 사람의 흔적이다 — 무엇을 골랐고 무엇과 견주었나,
|
||||
확인하지 못한 것이 무엇이고 그것이 어느 주장에 걸리나, 처음 생각과 어긋난 자리가 있나.
|
||||
|
||||
없는 사람을 만들지 마라. 「처음에는」·「고민 끝에」·「놀랍게도」를 자료 없이 쓰면 지어낸 것이다.
|
||||
넣은 문장마다 그것이 어느 파일 어느 줄에서 왔는지 댈 수 있어야 한다.
|
||||
자료에 흔적이 없으면 아무것도 넣지 말고 그렇게 보고해라. 그것도 이 단계를 한 것이다.
|
||||
|
||||
관문:
|
||||
node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
|
||||
node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
|
||||
python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
|
||||
node --experimental-transform-types \
|
||||
.agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
|
||||
node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
|
||||
|
||||
check_voice.mjs 는 목소리가 모자란지 재지 않는다. 지어낸 목소리를 잡는다.
|
||||
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함. 흔적이 없었으면 status DONE 에 notes 로 적어라.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## S7 — Studio 저장
|
||||
|
||||
```
|
||||
너는 Tech Log 파이프라인의 7단계를 맡는다.
|
||||
|
||||
먼저 .agents/skills/publishing-tech-log-to-studio/SKILL.md 를 끝까지 읽어라.
|
||||
references/studio-form-map.md 와 references/playwright-recipes.md 도 읽어라.
|
||||
|
||||
넣을 기록: <기록.md>
|
||||
도구: Playwright MCP (mcp__playwright__browser_*)
|
||||
|
||||
저장까지만 한다. 게시 버튼을 누르지 마라. 한 번 게시한 문서는 취소해도 삭제가 409 로 거절된다.
|
||||
|
||||
상태 레일 aside[class*="studio-document-status"] 가 25초 안에 안 뜨면 인증이 안 된 것이다.
|
||||
로그인 화면에 자격증명을 입력하지 말고 거기서 멈추고 사용자에게 알려라.
|
||||
|
||||
frontmatter 의 id 와 studio: 가 이미 있으면 그 주소로 가라. 새로 만들지 마라.
|
||||
|
||||
그림이 있으면 Asset 을 본문보다 먼저 올려라. 순서를 뒤집으면 미리보기가 본문을 막는다.
|
||||
|
||||
관문:
|
||||
상태 레일의 글자가 저장됨 으로 바뀌는 것을 확인 (최대 30초)
|
||||
python3 scripts/build-tech-log-tree.py <프로젝트>
|
||||
python3 scripts/verify-tech-log-tree.py <프로젝트>
|
||||
|
||||
저장됨 이 안 뜨면 버튼을 다시 누르지 말고 레일의 글자를 그대로 보고해라.
|
||||
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함. gates 에 저장 전후 version 을 적어라.
|
||||
```
|
||||
Reference in New Issue
Block a user