Files

T

2026-09-10 08:54:05 +09:00

9.1 KiB

Raw Permalink Blame History

name, description

name	description
running-tech-log-pipeline	Use when a codebase must go all the way to a saved Tech Log Studio draft — running the seven stages (SSOT, tree, record, diagram, prose, voice, Studio save) as separate subagents, one skill per stage, with a run ledger that records which skill each stage actually used and which gate it passed.

Tech Log 파이프라인 실행

이 스킬이 하는 일

스킬 일곱 개를 한 줄기로 잇는다. 각 스킬은 자기 단계만 알고 앞뒤를 모른다. 이 스킬이 단계 사이의 인계물과 순서와 관문을 정하고, 단계마다 서브에이전트를 하나씩 띄운다.

한 실행이 남기는 것은 산출물과 런 원장(runs/<프로젝트>/<runId>/run.json) 둘이다. 원장은 단계마다 어떤 스킬을 실제로 읽었고 어떤 관문을 어떤 종료 코드로 지났는지를 적는다. python3 scripts/verify-pipeline-run.py <원장> 이 그 원장을 검사한다.

원장이 이 스킬의 존재 이유다. 스킬을 안 읽고 쓴 글과 읽고 쓴 글은 결과물만 봐서는 구분되지 않는다. 원장은 그것을 기계가 구분할 수 있게 만든다.

왜 단계마다 서브에이전트인가

한 세션이 일곱 단계를 이어서 하면 앞 단계의 문맥이 뒤 단계로 새어 든다. 그러면 세 가지가 망가진다.

스킬을 안 읽고도 그럴듯하게 쓴다. 3단계에서 본문 규칙을 읽었으니 5단계에서 rewriting-technical-prose-naturally 를 열지 않아도 문장이 나온다. 스킬이 적용됐는지 확인할 방법이 사라진다.
관문이 형식이 된다. 자기가 쓴 글을 자기가 검사하면 실패를 「이건 예외」로 넘긴다.
어디서 어긋났는지 못 찾는다. 결과가 이상할 때 일곱 단계 중 어디가 원인인지 가릴 수 없다.

서브에이전트는 자기 단계의 입력 파일과 자기 스킬만 받는다. 다른 단계가 무엇을 했는지 모른다. 그래서 스킬을 안 읽으면 못 쓰고, 못 쓰면 원장에 남는다.

일곱 단계

#	단계	스킬	산출물
S1	코드베이스 → SSOT	`analyzing-codebase-for-tech-log`	`docs/<프로젝트>/final/document.md`
S2	SSOT → 분해 계약	`deriving-tech-log-root-tree`	`docs/<프로젝트>/tech-log-studio/tech-log-tree.json`
S3	글감 → 기록	`writing-tech-log-records`	`.../<주제>/<종류>/<기록>.md`
S4	기록 → 그림	`technical-visualizer`	`final/assets/<이름>/` · `final/.techviz/<이름>/`
S5	AI 티 제거	`rewriting-technical-prose-naturally`	같은 기록 파일 (제자리 수정)
S6	일한 사람의 목소리	`writing-as-the-person-who-did-it`	같은 기록 파일 (제자리 수정)
S7	Studio 저장	`publishing-tech-log-to-studio`	Studio 작업본 + `studio:` URL. 게시하지 않는다

단계마다의 입력·관문·원장 칸은 references/stage-contracts.md. 서브에이전트에 그대로 넣는 프롬프트는 references/subagent-prompts.md.

순서가 고정된 곳

세 자리는 바꾸면 결과가 틀어진다.

S3 → S4. 그림은 기록을 쓴 다음에 만든다. 무엇을 그릴지는 기록 본문이 정하고 (writing-tech-log-records/references/choosing-a-diagram.md 의 세 관문), 그림의 근거는 그 기록의 source 앵커가 가리키는 SSOT 절이다. 기록 본문이 그림의 소재를 고르고, SSOT 절이 그림의 사실을 댄다. 기록 .md 를 techviz prepare 에 넣지 않는다 — 기록은 SSOT 의 인용이라 줄 번호가 근거가 되지 못한다.

S4 → S5 → S6. 문장 손질은 본문이 다 찬 뒤에 한다. 그림을 붙이면 본문에 그림을 읽는 문단이 한둘 늘고, 그 문단도 같은 손질을 받아야 한다. S5 가 먼저다 — 번역투와 반복 문형을 걷어낸 뒤라야 S6 이 채울 자리(선택·비교·어긋남)가 보인다. 순서를 뒤집으면 S5 가 S6 이 넣은 목소리를 「과한 대구」로 다시 깎는다.

S6 → S7. Studio 에는 문장 손질이 끝난 것만 넣는다. 저장한 뒤에 고치면 Studio 쪽 version 이 올라가고 검증 산출물이 무효가 된다.

S5·S6 뒤에는 S3 관문을 다시 돌린다

문장을 고치면 본문 문법과 인용이 함께 움직인다. check_prose 가 error 0 이어도 check_body 가 깨지거나, 고쳐 쓴 코드블록 한 줄이 SSOT 와 달라져 check_evidence 가 걸린다.

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

원장에서는 이것이 S5·S6 의 관문이지 S3 의 재실행이 아니다.

건너뛰어도 되는 단계

이미 있는 것을 다시 만들지 않는다. 건너뛴 단계도 원장에 SKIPPED 와 사유를 적는다. 적지 않고 빠뜨린 것과 판단해서 건너뛴 것을 구분해야 한다.

단계	건너뛰는 조건
S1	`final/document.md` 가 있고 그 안에서 이 글감의 근거를 찾을 수 있다
S2	`tech-log-tree.json` 에 이 글감이 `PROMOTE` · `CONFIRMED` 로 이미 있다
S4	그림이 필요 없다(세 관문에 걸린다) 또는 `ssot-assets` 가 배정한 그림이 이미 있다
S7	사용자가 Studio 반입을 요청하지 않았다

S3·S5·S6 은 건너뛰지 않는다. 기록을 쓰는 단계와 문장을 고치는 두 단계는 이 파이프라인의 산출물 자체다.

실행 절차

0. 런을 연다

python3 scripts/verify-pipeline-run.py --init runs/<프로젝트>/<runId>/run.json \
  --project <프로젝트> --record <기록 경로>

runId 는 YYYY-MM-DD-HHMM 이다. 원장의 틀은 templates/run.json 이고, --init 이 그 틀을 채워 놓는다.

1. 단계마다 서브에이전트를 띄운다

프롬프트는 references/subagent-prompts.md 의 것을 쓴다. 프롬프트에 반드시 들어가야 하는 넷이 있다.

스킬 이름과 「먼저 그 SKILL.md 를 끝까지 읽어라」 — 요약을 주지 않는다. 요약을 주면 에이전트가 스킬을 안 연다.
자기 단계의 입력 파일 경로만. 앞 단계가 무엇을 했는지 설명하지 않는다.
관문 명령 원문과 「error 0 까지 고쳐라」.
스킬 영수증 — 그 SKILL.md 에서 자기 단계에 해당하는 규칙 한 줄을 원문 그대로 인용해 돌려보내게 한다. 이것이 스킬을 열었다는 기계 검증 가능한 증거다 (verify-pipeline-run.py 가 그 문자열이 실제 SKILL.md 안에 있는지 대조한다).

한 단계가 끝나면 그 결과를 원장에 적고 다음 단계를 띄운다. 단계를 병렬로 띄우지 않는다 — S1~S7 은 앞 단계의 산출물이 뒤 단계의 입력이다. 병렬이 되는 것은 같은 단계 안에서 서로 다른 기록 여러 건을 처리할 때뿐이다.

2. 원장을 검사한다

python3 scripts/verify-pipeline-run.py runs/<프로젝트>/<runId>/run.json

error 0 이어야 런이 끝난 것이다. 이 검사기가 보는 것은 결과물의 품질이 아니라 절차의 준수다 — 단계가 빠졌는지, 스킬 영수증이 그 스킬의 실제 문장인지, 관문이 돌았고 종료 코드가 0 이었는지, 적어 낸 산출물이 디스크에 있는지.

3. 프로젝트 검사기를 돌린다

python3 scripts/verify-tech-log-tree.py <프로젝트>
python3 scripts/verify-project-layout.py <프로젝트>
python3 scripts/audit-records.py <프로젝트>
python3 scripts/check-figure-text.py <프로젝트>

이 스킬이 하지 않는 것

판단을 대신하지 않는다. 어떤 후보를 PROMOTE 할지, 그림이 필요한지, 어떤 종류인지는 각 단계의 스킬이 정한다. 이 스킬은 그 스킬이 실제로 불렸는지만 본다.
관문을 완화하지 않는다. 관문이 error 를 내면 그 단계는 끝나지 않은 것이다. 원장에 FAILED 로 적고 멈춘다. 다음 단계로 넘기지 않는다.
게시하지 않는다. S7 은 저장까지다. 게시는 사람이 공개 화면을 보고 판단한다.

자주 어긋나는 자리

증상	원인	원장에 남는 모습
문장이 여전히 AI 같다	S5 를 같은 세션이 겸했다	`skillEcho` 가 비었거나 SKILL.md 에 없는 문장
그림 안에 문장이 있다	S4 가 `check-figure-text.py` 를 안 돌렸다	관문 목록에 그 명령이 없다
SSOT 에 없는 인용이 있다	S3 이 앞 기록에서 코드를 옮겨 적었다	`check_evidence` 종료 코드 ≠ 0
기록이 색인에 없다	S2 를 건너뛰고 S3 을 했다	S2 가 `SKIPPED` 인데 사유가 없다
Studio 에서 그림이 안 보인다	S7 이 Asset 을 올리기 전에 본문을 넣었다	S7 관문에 미리보기 확인이 없다

9.1 KiB Raw Permalink Blame History