feat: 가상화 문서들 추가
This commit is contained in:
DongHyeonka
@@ -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