모델이 초안 작성한 문서의 인계 기록: 두 개의 레인과 누가 무엇을 썼는지 계산하는 스크립트

대부분의 문서화 파이프라인은 모델이 글쓰기를 못해서 실패하는 것이 아니라, 누가 어떤 부분을 쓸 수 있었는지 아무도 기록하지 않기 때문에 실패합니다. 팀은 전체 페이지를 모델에 넘기고 그럴듯한 산문을 돌려받지만, 나중에 속도 제한(rate limits)에 대한 자신감 있는 단락이 확인된 적이 없다는 것을 발견하는 경우가 있습니다. 핸드오프 로그(handoff log)는 정책 파일보다 훨씬 적은 형식으로 이를 해결합니다: 모든 섹션은 레인(lane), 증거 스탬프(evidence stamp)를 가지며, 스프린트가 끝날 때 합산할 수 있는 CSV의 한 행을 가집니다.

다음 내용은 참조 문서화를 위한 두 개의 레인 생성 워크플로우와 분할 비율을 보고하는 작은 표준 라이브러리 스크립트를 포함합니다. 레인 규칙이 전체 설계이며, 스크립트는 이 규칙을 보이게 하고 로그가 조용히 허구 속으로 표류하는 것을 막기 위해 존재합니다.

레인 규칙: 재도출 가능하거나 소유된 부분

어떤 주장은 독자가 저장소(repository)에 무언가를 실행하여 재도출할 수 있을 때 초안 레인(draft lane)에 속합니다. '재시도는 2초 기본 지연 시간에서 기하급수적으로 감소한다'는 주장은 grep -n base_delay src/retry.py가 상수를 반환하면 작성 가능합니다. 어떤 주장은 오직 사람만이 책임질 수 있을 때, 즉 왜 특정 기본값이 선택되었는지, 무엇이 사용 중단(deprecated)되었고 무엇으로 대체되는지, 어떤 실패 모드를 무시해도 안전한지, 그리고 '하지 마십시오(do not)'라는 문구를 포함하는 모든 문장에서 속합니다.

그 분할은 의도적으로 거칩니다. 섹션 수준의 세분성은 오후에 계획하기에 충분히 거칠고, 잘못 할당된 섹션이 조용한 사실적 오류가 아닌 검토 의견 불일치로 나타나기에 충분히 미세합니다. 아래 표가 전체 기준입니다. 적어도 두 번의 스프린트를 두 개의 레인으로 실행해 보기 전까지는 세 번째 레인을 추가하는 것을 삼가십시오.

1. 프롬프트 작성 전에 개요를 고정하세요. 페이지를 150~400단어 섹션으로 분할하고 각 섹션에 03-retries와 같은 안정적인 ID를 부여합니다. 스프린트를 거쳐 살아남는 ID가 나중에 로그를 diff에 연결할 수 있게 해줍니다.
2. 섹션별로 제한된 증거 팩을 구축하세요. 모델에게 전체 리포지토리 대신 개요 슬라이스, 마지막 릴리스에서 수정된 파일들, 그리고 테스트 로그 하나를 제공합니다. 바이트 예산은 팩이 감사 가능하게 유지하고, “모델이 알 방법이 없었다”라는 주장을 검증 가능한 주장으로 바꿔줍니다.
3. 초안 레인 섹션만 작성하세요. 섹션 본문과 각 사실적 문장을 뒷받침하는 정확한 명령어를 요청합니다. 모델이 명령어를 명시할 수 없다면, 해당 문장은 초안(draft) 대신 사람(human)의 영역으로 이동합니다.
4. 사람 영역 섹션은 처음부터 작성하세요. 모델을 독자로 참고하는 것은 괜찮지만, 그 산문을 복사해서 붙여넣는 것은 안 됩니다. 왜냐하면 이 영역의 요점은 검토 과정에서 사람이 모든 단어를 방어할 수 있어야 하기 때문입니다.
5. 스프린트가 끝나기 전에 각 섹션을 동일한 CSV에 기록하세요. 일주일 후에 기억으로부터 재구성된 기록은 추측일 뿐이며, 동시대성이 로그를 보관할 가치가 있게 만드는 유일한 속성입니다.
6. 총계보다 보고서를 실행하고 위반 사항을 먼저 읽으세요. 레인 규칙 위반 사항이 더 중요합니다. 왜냐하면 그것들은 어떤 섹션이 실제로 어느 영역에 할당될 수 없었는지를 표시하기 때문입니다.

로그 스키마와 증거 팩

첫 번째 스프린트에는 section_id,title,lane,evidence,words,minutes,model_calls의 일곱 개 열만으로 충분합니다. 아래 행들은 실제 스프린트 측정치가 아니라 형식 예시일 뿐이므로, 어떤 결론을 도출하기 전에 모든 값을 본인의 것으로 교체해야 합니다.

section_id,title,lane,evidence,words,minutes,model_calls
02-auth,Authenticating requests,draft,cmd:pytest -q tests/test_auth.py,320,25,3
03-retries,Retry behaviour,draft,cmd:grep -n base_delay src/retry.py,240,18,2
...

패키지 빌더(pack builder)는 입력값이 이미 가지고 있는 파일들로만 구성되어 있기 때문에 셸 스크립트입니다. 의도적으로 손실적(lossy)으로 설계되었는데, 잘림 현상이 출력 파일에 보이므로 검토자가 모델이 전체 구조를 보았는지 아니면 요약본만 보았는지를 알 수 있습니다.

#!/usr/bin/env bash
# pack.sh <section-id> - build a bounded evidence bundle for one section
set -euo pipefail
...

리포트 스크립트 (The report script)

아래 스크립트는 표준 라이브러리만을 사용하는 순수 Python 3으로, 한 번에 감사하기에 충분히 작습니다. 이 스크립트는 레인(lane)들의 합계를 계산하고, 단어당 분(minutes per hundred words)을 산출하며, 레인 규칙을 위반하는 모든 행을 출력합니다. --strict 옵션은 나중에 그러한 동작을 원할 경우 해당 위반 사항이 CI 단계에서 실패하도록 만듭니다.

#!/usr/bin/env python3
"""handoff_report.py - summarize a documentation sprint handoff log.

...

위의 플레이스홀더 행들에 대해 실행하면 아래와 같은 산술 결과가 출력됩니다. 이는 귀하의 열(column) 이해도가 저와 일치하는지에 대한 확인일 뿐, 초안 작성 비용에 대한 발견 사항은 아닙니다.

lane    sec   words      w%      min      m%  min/100w
draft     2     560   48.7%     43.0   22.9%       7.7
human     2     590   51.3%    145.0   77.1%      24.6
...

무료 옵션이 적용되는 곳 (Where the free options fit)

2단계와 6단계는 귀하의 리포지토리와 테스트 로그에 접근하며, 어느 쪽도 영구적인 머신을 필요로 하지 않습니다. 초안 작성(Drafting)이야말로 모델 액세스가 진정으로 유용하게 활용되는 부분입니다. 패키지는 작고, 섹션들은 독립적이며, 잘못된 초안은 재빌드된 파이프라인 전체를 비용으로 지불하는 대신 한 번의 재생성(regeneration)만 비용으로 합니다. 고지: 본 기사는 MonkeyCode의 제품 홍보(product outreach)의 일환으로 작성되었습니다. 무료 모델 액세스와 무료 서버 옵션의 가용성은 운영자(operator)가 제공하며, 저는 여기서 모델 이름, 할당량(quota), 하드웨어 또는 기간을 측정하지 않았으므로, 습관처럼 사용하기 전에 현재 약관을 확인하십시오.

무료 서버는 pack.sh와 폐기할 수 있는 클론에 대한 보고서를 실행하기에 방어적인 장소입니다. 왜냐하면 두 스크립트 모두 CI 비밀(secrets)이나 릴리스 태그가 필요하지 않기 때문입니다. CSV 파일은 버전 관리에 보관하고, 패키지(packs)는 제외해야 합니다. 패키지는 크고 테스트 로그를 포함하며 ID만으로 재구축할 수 있기 때문입니다.

한계점 및 건너뛰어야 할 경우

• 로그는 정확도가 아닌 노력을 측정합니다. 사실 오류가 세 개 있는 저렴한 초안 레인(draft lane)은 좋지 않은 거래이며, 총합이 아니라 검토 의견 불일치만이 이를 드러냅니다.
• 완전히 재작성된 섹션은 인간 레인(human lane)에서 다시 기록되어야 합니다. 그렇지 않으면 보고서가 초안 레인을 과대평가하게 됩니다. 그러면 스크립트가 누락된 human: 도장을 표시하는데, 이는 버그가 아니라 올바른 결과입니다.
• 단일 진실 공급원(single source of truth)에서 생성된 문서는 거의 이 과정이 필요하지 않습니다. OpenAPI 파일이나 스키마 레지스트리가 이미 페이지를 발행하는 경우, 모델이 병목 지점(bottleneck)이 아니며 출력은 구조적으로 재파생될 수 있습니다.
• 소규모 팀은 건너뛰어야 합니다. 주당 약 한 페이지 미만의 문서라면, 로깅 오버헤드가 로그가 절약해 주는 것보다 커지므로 짧은 검토 체크리스트가 더 저렴합니다.
• 규제되거나 계약적인 문서는 적합하지 않습니다. 진술(statement)별 공식 승인은 초안 대응물이 없는 인간 레인 활동이므로, 기준표 자체가 무너집니다.

숫자가 알려줄 수 있는 것과 알려줄 수 없는 것

단어 수와 레인당 분은 스프린트의 시간이 실제로 어디에 쓰였는지 알려줍니다. 하지만 그 페이지가 현재 정확한지 여부에 대해서는 아무것도 말해주지 않습니다. 먼저 위반 사항(violations)을 읽고, 유사한 위험도를 가진 섹션 간의 min/100w를 비교하며, 10분 미만의 격차는 느린 검토에서 오는 노이즈로 취급하십시오. 만약 이런 방식으로 스프린트를 진행한다면, 상황이 나빠지더라도 로그는 유지해야 합니다. 왜냐하면 문제가 터진 섹션이야말로 다음 스프린트의 레인 비용을 책정하는 곳이기 때문입니다.