반복되는 지시를 스킬로 옮기고 검사 패턴 붙이기

프롬프트에 적은 규칙은 그 대화에서만 듣는다. 다음 세션은 같은 것을 모른다.

같은 지시를 몇 번째 쓸 때 문서로 옮겨야 하나?

게시판 API 를 아홉 단계로 만드는 동안 스킬 여섯과 서브에이전트 하나가 나왔다. 옮긴 시점과 경계를 나눈 기준을 남긴다.

1. 스킬로 옮기는 시점

세 번째다. 두 번은 우연일 수 있다. 세 번째면 앞으로도 나온다.

추출에도 고정 비용이 든다. 문서가 하나 는다. 그 문서를 언제 읽을지 description 에 적어야 하고 다른 스킬과 겹치지 않는지도 봐야 한다. 두 번으로는 그 비용을 못 넘는다.

표 1. 이 작업에서 나온 스킬 여섯

2. 스킬 경계를 나누는 기준

경계가 흐리면 에이전트가 두 문서를 다 읽거나 둘 다 안 읽는다.

그래서 description 에 담당하지 않는 일을 같이 적는다.

code-doc-pairing  … 단계 전체를 도는 것은 curriculum-step 이 맡는다.
curriculum-step   … 문서 규약은 code-doc-pairing, 검사 규약은 verification-scripts 가 맡는다.

셋은 한 작업의 세 층이다. curriculum-step 이 한 단계를 끝까지 돌린다. 그 안에서 문서는 code-doc-pairing 이 맡고 검사는 verification-scripts 가 맡는다. 넘기는 자리를 문서에 적어 두면 읽는 쪽이 고민하지 않는다.

언제 읽을지를 문서가 스스로 말한다

경계만큼 중요한 것이 언제 열리느냐다. description 에 실제로 할 법한 말을 그대로 적는다.

"N단계 진행해", "다음 단계", "4단계 해줘", "커리큘럼 이어서" 라고 하거나
docs/0N-*.md 를 새로 쓸 때 실행한다.

사람이 쓰는 말과 코드가 바뀌는 자리 둘을 같이 적는다. 앞쪽은 부를 때 열리게 하고, 뒤쪽은 부르지 않아도 열리게 한다. code-doc-pairing 은 server/src 나 web/src 의 파일을 고친 뒤라고 적혀 있다. 문서를 맞추라고 말하지 않아도 그 자리에서 열린다.

한 단계를 한 벌로 묶는다

curriculum-step 이 묶은 것은 일곱이다. 구현과 게이트 검사와 회귀, 실측값 수집, 단계 문서, 코드↔문서 매칭, 명세 동기화다.

하나씩 지시하면 끝의 둘이 빠진다. 구현이 끝나면 돌아간다는 느낌이 들어서다. 한 벌로 묶어 두면 문서와 명세가 코드와 같은 커밋에 들어간다.

3. 규칙만 적으면 다시 샌다

스킬에 규칙만 늘어놓으면 다음에 같은 실수가 돌아온다. 규칙은 지켜야 할 이유를 안 들고 있다.

그래서 실제로 난 사고를 같이 적는다.

표 2. 스킬별로 담은 실제 사고

browser-verify-traps 는 통째로 사고 기록이다. 무한 스크롤이 안 돌아 코드를 세 번 고쳤다. 원인은 탭이 화면에 안 보이는 상태였다. 그 상태에서는 IntersectionObserver 가 돌지 않고 TanStack Query 의 재시도도 멈춘다. 코드는 처음부터 맞았다.

4. 검사 패턴이 없는 규칙의 수명

문서에만 적힌 규칙은 지워진다. 실제로 그랬다.

blog-voice 에 금지어를 적어 두었다. 그런데 31편을 윤문하는 동안 같은 낱말이 13곳으로 다시 들어왔다. 규칙이 문서에만 있고 검사에는 없었다.

그래서 규칙을 적을 때 검사도 같이 붙인다.

grep -nE '(것들이다\.|정리하면 다음과 같다|아래[는가] [^.]{0,20}다\.)' <원고.md>

오탐이 나면 오탐으로 둔다. 정규식이 참·거짓을 가릴 수 없는 자리가 있다. 검사는 눈으로 볼 자리를 짚어 줄 뿐이다. 판정은 사람이 한다.

code-doc-pairing 의 검사는 네 줄이다. 코드에서 문서로 가는 링크, 문서 안의 상대 링크, 금지어, 그리고 절 개수. 문서를 고친 뒤 이 넷을 돌린다.

5. 전역에 둘 것과 프로젝트에 둘 것

기준은 다음 프로젝트에서도 같은가다.

표 3. 전역과 프로젝트의 구분

handwork-hero-image 는 애매한 자리였다. 절차는 어디서나 같은데 화풍과 파일 경로가 handwork 것이다. 화풍이 규약의 절반이라 프로젝트로 뒀다.

6. 서브에이전트로 뺀 일

문서 여러 개를 동시에 고치는 일만 에이전트 정의로 뺐다.

tools: Read, Write, Edit, Grep, Glob, Bash
disallowedTools: Agent

에이전트를 부를 권한을 뺐다. 문서를 쓰는 에이전트가 또 에이전트를 띄울 이유가 없다. 띄우면 누가 어느 파일을 들고 있는지 추적이 끊긴다.

브리핑에는 매번 달라지는 셋만 넣는다. 담당 파일 목록, 실측값 표, 무엇이 바뀌었나. 나머지 고정값은 에이전트 정의와 code-doc-pairing 이 들고 있다.

실측값을 안 주면 그럴듯한 숫자를 지어낸다. 그래서 값을 브리핑에 전부 실어 보내고 에이전트는 스스로 재지 않는다. 서버와 DB 가 본 작업과 충돌하기 때문이다.

7. 이 방식의 비용과 한계

스킬이 늘수록 예외를 설명할 자리가 는다. 새 상황이 규약과 어긋나면 그 자리에서 규약을 고칠지 예외로 둘지 판단해야 한다.

경계를 잘못 나누면 더 나쁘다. 두 스킬이 같은 일을 다르게 적어 두면 읽는 쪽이 둘 다 읽고 섞는다. 문서 하나였을 때보다 못하다.

검사는 오탐을 낸다. 정규식이 문장의 뜻을 모른다. ~것들이다 를 걸러 보니 여덟 건이 나왔는데 대부분 뒤에 실제 값이 이어지는 정상 문장이었다.

사고 기록이 쌓이면 문서가 길어진다. 143줄짜리 스킬을 매번 읽는 비용이 든다. 아직 줄일 자리를 찾지 못했다.

8. 스킬이 실제로 막은 것

readme-stack 을 쓴 뒤로 배지 버전을 추측하지 않는다. 값은 package.json 에서 읽는다. 노트북에 깔린 도구는 스택에 넣지 않는다.

verification-scripts 를 쓴 뒤로 측정 중에 회귀를 돌리지 않는다. 그 스크립트가 시드를 지운다는 사실이 문서 맨 위에 경고로 있다.

code-doc-pairing 의 검사 네 줄은 매 단계 돈다. 코드 파일마다 첫 줄에 짝 문서 경로가 있고 문서 첫 줄에 소스 경로가 있는데, 아홉 단계를 지나는 동안 끊긴 링크가 한 번도 안 나왔다. 문서 40여 편이 코드와 같은 커밋에서 움직였다는 뜻이다.

handwork-hero-image 는 컬렉션을 먼저 가르게 한다. Cases 는 무광 3D 렌더고 Labs 는 플랫 벡터다. 화풍을 확인하지 않고 만들면 목록에서 그 한 장만 튄다. 실제로 Labs 이미지를 만들기 전에 기존 파일을 열어 보고 나서야 두 화풍이 다르다는 것을 알았다.

막지 못한 것도 있다. 검사 스크립트를 레포로 옮긴 첫 실행에서 16개 중 8개가 실패했다. 값을 꺼내는 헬퍼가 없는 값에 undefined 라는 다섯 글자를 찍었다. 받는 쪽은 그걸 토큰으로 읽었다. 그 패턴은 어느 스킬에도 없었다.

추가로 확인할 사항

스킬 여섯 중 다음 프로젝트에서 실제로 쓰이는 것이 몇 개인지는 아직 모른다. 전역에 둔 둘은 바로 쓰인다. 프로젝트 셋은 이 레포와 함께 끝날 수도 있다.

같은 것을 다시 한다면 사고 기록을 먼저 모으겠다. 규칙은 그 뒤에 따라온다.