방법론을 처음 내놓고, 두 시간 만에 다시 냈다

2026.10.18 게시

이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.

방법론을 처음 내놓고, 두 시간 만에 다시 냈다 — 새벽 2시 23분에 문서 세 장만 든 얇은 상자 preview.1을 냈고, 4시 26분에 절차와 Skill, eval 사례, 설치 도구까지 든 상자 preview.2를 다시 냈다

지난 글 끝에서, 설계 단계 승인을 공통에서 빼고 남긴 세 문장이 다음 날 방법론을 처음 공개할 때 그대로 들어갔다고 적었다.

이번 글은 그 공개 이야기다. 10월 17일 새벽 2시 23분에 첫 공개본(preview.1)을 냈고, 두 시간 뒤인 4시 26분에 두 번째 공개본(preview.2)을 냈다. 왜 급하게 냈는지, 내기 전에 무엇을 정했는지, 그리고 왜 두 시간 만에 다시 냈는지를 적는다.


왜 공개본이 필요했나

흐름은 단순했다.

지금까지 차세대 방법론은 개인 프로젝트 하나에만 적용해 왔다. 12~20편이 그 기록이다. 그러다 다음 주 월요일(10월 19일)부터 회사 일에도 이 방법론을 반영해 볼 기회가 생겼다.

회사 쪽에서 쓰려면 어딘가에서 받아 가야 한다. 그런데 18편에서 정한 대로, 방법론을 설계하고 실험하는 연구 저장소는 어떤 프로젝트도 직접 읽지 않는다. 비공개이기도 하고, 거기서 바로 읽으면 실험 중인 내용이 그대로 흘러 들어간다. 그래서 공개 저장소에 열어 두고, 회사 프로젝트가 태그를 고정해서 받아 가게 했다.

이렇게 한 진짜 이유는 데이터다. 19편에서 방법론을 고치려면 실제 작업 기록이 근거가 돼야 한다고 적었다. 그런데 지금까지 그 기록은 개인 프로젝트 한 곳에서만 나왔다. 회사 일에도 같은 방법론을 붙이면, 성격이 다른 두 곳에서 관측을 모을 수 있다. 1~11편은 회사 일, 12~20편은 개인 프로젝트였는데, 이제 두 곳을 같이 보게 된다.

공개 경로. 연구 저장소의 공통 원칙은 검토한 파일만 공개 저장소의 v1-preview branch로 옮겨 preview.1 태그를 달았다. 두 시간 뒤 앱 전용 규칙 저장소에서 실행 절차와 Skill, eval을 제품 종속 부분만 덜어 내 옮겨 preview.2 태그를 달았다. 공개 main은 v0.2 그대로다. 회사 프로젝트는 태그를 고정해 복사하고 설치 도구로 프로젝트 문서를 만든다. 공통에 빠진 것은 회사 공개 정책을 확인한 뒤 일반화한 것만 다음 preview로 올린다. 연구 저장소를 프로젝트가 직접 읽는 길은 없다


내놓기 전에 정한 것

무엇을 어떻게 낼지는 여섯 가지로 나눠 정했다.

  정한 것 누가
담을 범위 문서 세 개와 해시 목록, 커스터마이징 안내만. 연결 도구는 뺀다 Agent 제안대로
위치 별도 branch의 태그로 낸다. 기존 사용자가 쓰는 main(v0.2)은 그대로 둔다 Agent 제안대로
언어 영어와 한국어를 같이 낸다 내가 정함(Agent는 권하지 않음)
묶음 정리 특정 제품이나 비공개 자료에 기대는 문장을 걷어 내 단독으로 읽히게 한다 Agent 제안대로
커스터마이징 안내 사본을 받아 어댑터를 채우고 Agent에게 일을 시키는 순서를 새로 쓴다 Agent 제안대로
사람 판단 20편의 세 문장을 core.md에 넣는다 Agent 제안대로

마지막 줄이 20편과 이어지는 곳이다. 공개본에는 예전 v0.2에 있던 위험 등급과 리뷰 단계가 없다. 세 문장을 넣지 않으면 외부 사용자에게 보이는 사람 판단 규칙이 하나도 없게 된다.

이 검토안도 처음엔 독립 리뷰에서 FAIL을 받았다. 막힌 이유는 두 가지였다.

  • 다음 주에 필요한 건 태그 하나인데, 공개 main을 새 방법론으로 바꾸는 일까지 같이 묶었다. 그러면 태그 없이 저장소 주소로 가져다 쓰던 기존 사용자가 받는 내용이 조용히 바뀐다.
  • 공개 저장소에 branch나 PR을 올리는 순간 이미 공개다. 그런데 공개 전 확인이 main 병합과 태그 직전으로 잡혀 있었다.

그래서 main은 그대로 두고 별도 branch에만 올리기로 바꿨고, 공개 전 확인은 첫 push 전으로 옮겼다.

언어 결정은 그 뒤에 한 번 더 바뀌었다. 처음엔 영어 저장소와 한국어 저장소에 따로 내기로 했다가, 같은 날 한 저장소로 묶었다. 영문을 기준으로 두고 한국어판은 ko/ 아래에 둔다.


공개 태그는 옮길 수 없어서

태그는 한 번 공개하면 옮기거나 지우지 않기로 했다. 누가 이미 그 태그를 고정해 받아 갔는지 알 수 없어서다. 그래서 공개 전에, 공개할 내용만으로 커스터마이징 안내를 처음부터 따라 해 봤다.

준비한 건 가상의 작은 Python 예제 프로젝트 하나다. 테스트 하나, CI 파일 하나, 규칙 두 줄짜리 AGENTS.md. 회사 코드는 쓰지 않았다. GitHub 태그 압축 파일과 같은 모양으로 로컬 압축 파일을 만들어 Windows PowerShell 5.1에서 안내 그대로 실행했다.

해 본 것 영어판 한국어판
안내대로 사본 복사 성공 성공
해시 대조 세 문서 일치 세 문서 일치
대조군: 줄바꿈 고정 없이 core.autocrlf=true로 받기 세 문서 불일치 세 문서 불일치
안내대로 줄바꿈 고정을 넣고 받기 세 문서 일치 세 문서 일치

줄바꿈은 18편에서 두 번 걸렸던 문제다. 내용으로 해시를 만드는 이상, Windows에서 받는 순간 CRLF로 바뀌면 다른 버전이 된다. 이번엔 대조군을 일부러 만들어서, 그 함정이 실제로 생기는 것과 안내에 넣은 한 줄이 그걸 막는 것을 둘 다 확인했다.

.adaptive-sdd/methodology/** text eol=lf

안내의 Agent 프롬프트도 앞의 두 단계까지 돌려 봤다. ① 코드를 고치지 않고 사실만 모으는 관찰과 ② 어댑터 초안이다. 어댑터는 프로젝트마다 다른 값을 적는 파일이고, 공통 사본은 건드리지 않는다.

두 판 모두 Agent가 코드를 고치지 않았고, 자리마다 제안 값과 근거, 확인하지 못한 것을 나눠 냈다. 마음에 든 건 사람이 정해야 할 것을 정하지 않고 모아 왔다는 점이다. 영어판은 9개, 한국어판은 8개였다. 종료 판정, 쓰기 범위, 사람 판단 지점 같은 것들이다. 세 번째 문장(“Agent는 사람이 하지 않은 결정을 만들지 않는다”)이 적어도 이 두 번에서는 지켜졌다.

그렇게 새벽 2시 23분, 공개 저장소의 v1-preview branch에 v1.0.0-preview.1을 pre-release로 냈다.


내놓자마자 나온 구멍

공개된 상태 그대로 별도 세션에 리뷰를 맡겼더니, 바로 구멍이 나왔다. 무거운 것만 셋이다.

  구멍 왜 문제인가
B1 core.md 첫머리는 “호스트·프로젝트 규칙을 먼저 따른다”인데, “사람 판단” 절은 “면제하지 못한다”다. 둘 중 무엇이 우선인지 한곳에서 정하지 않았다 사람에게 물을 수 없는 환경에서 Agent가 어느 쪽을 따를지 갈린다
B2 “사람 판단이 필요한 질문”이 언제 생기는지 최소 조건이 없다 첫 번째 문장이 언제 발동하는지 Agent마다 다르게 읽을 수 있다
B3 core.md는 작업 기록의 기준 위치를 정하라고 요구하는데, 어댑터에 그걸 적을 자리가 없다 안내의 ⑤ 시운전이 그 자리를 전제한다

공교롭게도 셋 다 이번에 새로 넣은 사람 판단과 작업 기록 쪽이다.

처음에는 이걸 다음 판으로 미루고, 월요일에는 어댑터에 직접 적어서 피해 가려고 했다.


글만으로는 일을 시킬 수 없었다

그런데 구멍보다 더 큰 게 보였다. preview.1은 글뿐이었다.

관측하고 적응하라는 원칙은 있는데, Agent가 실제로 작업을 만들고, 나누고, 구현하고, 끝내는 절차가 없었다. 보조 절차가 도움이 되는지 비교할 eval 형식도, 관측에서 개선으로 이어지는 순서도 없었다. 월요일에 회사 프로젝트에 붙이면, 그 빈자리를 거기서 새로 채워야 했다.

그런데 그 부분은 이미 있었다. 개인 프로젝트에서 오래 다듬어 온 절차와 Skill, eval이 18편에서 만든 앱 전용 규칙 저장소에 들어 있었다. 그래서 이렇게 정했다.

  • 새로 쓰지 않는다. 이미 돌려 본 것에서 가져온다.
  • 프로젝트에 종속된 부분만 덜어 내고, 그 자리는 설치할 때 프로젝트에 맞게 채운다.
  • 월요일에 되는 것부터 낸다.

preview.1을 낼 때 “문서만 담는다”고 정했으니, 두 시간 만에 그 범위를 내가 넓힌 셈이다.

  preview.1 (02:23) preview.2 (04:26)
공통 원칙 core.md 등 문서 세 개 같은 문서에 B1~B3 반영
실행 절차 없음 절차 문서와 Skill 4개(작업 정리, 작업 격리, 설계와 구현, 검증과 종료)
eval 없음 eval 형식과 가상 사례 30개
설치 안내를 보고 손으로 복사하고 어댑터 작성 설치 도구가 프로젝트 값으로 프로젝트 문서와 Skill 입구를 생성
판 영어·한국어 같음 절차·설치 도구는 한국어판만. 영어판은 다음 판으로

옮기면서 가장 손이 많이 간 건 제품에 묶인 부분이었다. 앱에서 쓰던 절차는 GitHub 이슈와 라벨, 앱의 빌드 환경, 앱의 경로를 전제로 쓰여 있었다. GitHub 조작은 작업 관리 방식별 대응표(로컬 문서, GitHub)로 바꿔 읽게 했고, 제품 사실은 프로젝트 값 파일(project.json)에서 생성하는 프로젝트 문서로 뺐다.

eval 사례도 그대로 옮길 수 없었다. 앱에서 쓰던 사례 197개는 비공개 앱의 기능과 모듈을 담고 있다. 대신 같은 기대 행동을 가상 프로젝트로 옮긴 사례 30개를 뒀다.

설치 흐름은 이렇다. 사본을 바이트 그대로 받아 두고, 값을 채운 뒤 생성하고, 검사한다.

python -I -B .adaptive-sdd/tools/install.py init --project-root .
python -I -B .adaptive-sdd/tools/install.py render --project-root . --source-tag v1.0.0-preview.2 --source-commit <SHA>
python -I -B .adaptive-sdd/tools/install.py check --project-root .

render는 고정 사본이 해시 목록과 다르면 생성을 거부한다. 사람이 손으로 고친 생성물은 덮어쓰지 않고 그대로 뒀다고 알린다.

B1~B3도 이 판에서 고쳤다. 사람 판단 절의 세 번째 문장 뒤에 위임 이야기가 붙었고, 마지막에 사람에게 물을 수 없을 때의 처리가 들어갔다.

  1. Agent는 사람이 하지 않은 결정을 만들지 않는다. 리뷰 통과, 테스트 통과, 일반 진행 지시, 침묵을 사람의 결정으로 대신하지 않는다. 프로젝트 설정에 사람이 범위·날짜·확인자를 적어 둔 위임은 그 범위 안에서 사람의 결정이다. 범위 없는 진행 지시는 위임이 아니다. Agent는 위임을 만들거나 넓히거나 확정하지 않는다.

이 세 가지는 공통 최소 요건이다. 호스트·프로젝트 규칙은 이 요건을 더 엄격하게 할 수 있지만 면제하지 못한다. 충돌하면 그 판단에 의존하는 작업을 멈추고 사람에게 묻는다. 사람에게 물을 수 없는 실행 환경이면 그 작업을 멈추고 질문을 미결로 기록한다.


시운전에서 나온 빈 확인자

preview.2도 공개 전에 가상 프로젝트에 설치해 봤다. 이번엔 모듈이 여러 개인 프로젝트에, 기존 AGENTS.md와 CLAUDE.md가 있는 상태로 넣었다. 기존 내용은 생성 구간 밖에 그대로 남았고, 설치·생성·검사 모두 통과했다.

그런데 하나가 걸렸다. project.json의 목록 값에 항목마다 어떤 키를 써야 하는지 안내에 없었다. 추측한 키로 쓰면 오류 없이 빈 칸으로 생성됐다.

특히 위임이 문제였다. 확인자 칸이 빈 채로 생성됐는데, 생성된 문서에서는 그게 “기록된 위임”처럼 보였다. 방금 넣은 문장이 “사람이 범위·날짜·확인자를 적어 둔 위임만 사람의 결정”인데, 설치 도구가 그 모양을 확인자 없이 만들어 낸 것이다.

그래서 설치 도구가 목록 값의 형식을 검사하게 고쳤다. 정해진 키만 받고, 빈 값은 거부한다.

"human_judgment": {
  "delegations": [
    { "scope": "위임 범위", "date": "YYYY-MM-DD", "confirmed_by": "기록한 사람" }
  ]
}

키가 다르거나 값이 비면 render가 생성을 거부한다. 고친 판으로 버전 올리기 경로까지 다시 따라 해 봤고, 추측한 키는 거부됐다.

독립 리뷰는 막을 문제는 없다고 봤고, 고칠 것으로 지적한 여덟 가지는 공개 전에 고쳤다. 내가 게시를 확인한 뒤 새벽 4시 26분에 v1.0.0-preview.2를 냈다. 공개 뒤 실제 GitHub 압축 파일로 새 가상 프로젝트에 다시 설치해 검사까지 통과하는 것을 확인했다.


아직 안 한 것

해 본 만큼만 적어 둔다.

  • 안내의 Agent 프롬프트는 preview.1에서 ①②까지만 돌렸다. ③~⑥(사람 결정, 쓰고 생성하기, 작은 작업 시운전, 실작업 뒤 개선)은 돌려 보지 않았다.
  • 시운전은 Windows에서만 했다. macOS와 Linux는 하지 않았다.
  • Skill이 실제로 기대한 대로 행동하는지 모델을 돌려 확인하는 eval은 하지 않았다. 사례 형식 검사까지만 했다.
  • 영어판은 절차와 설치 도구가 빠진 채다. 영어 초안은 따로 만들고 있고 아직 공개하지 않았다.
  • 리뷰는 모두 작성에 참여하지 않은 같은 제공사의 다른 Agent가 했다.
  • 공개 저장소의 star와 fork는 0이다. 효과, 그러니까 결과나 재작업이나 비용이 나아지는지는 재지 않았다. 공개 README와 변경 기록에도 그렇게 적었다.

정리

한 것 결과
공개한 이유 개인 프로젝트와 회사 일, 두 곳에서 데이터를 모으려고. 회사 쪽은 공개 태그를 고정해 받아 간다
preview.1 문서 세 개와 안내만. 별도 branch의 태그로 냈고 main(v0.2)은 그대로
공개 전 시운전 복사·해시·줄바꿈과 Agent 첫 두 단계까지 확인
공개 뒤 리뷰 사람 판단과 작업 기록 쪽 구멍 셋
preview.2 두 시간 뒤. 앱에서 다듬은 절차·Skill·eval을 옮기고 설치 도구를 붙였다. 구멍 셋도 고쳤다
preview.2 시운전 확인자 없는 위임이 생성되는 걸 찾아 막았다
효과 재지 않았다

preview.1의 “문서만”은 Agent가 제안하고 내가 받아들인 범위였다. 막상 내고 나니 글만 있는 공개본으로는 월요일에 Agent에게 일을 시킬 수 없었고, 개인 프로젝트에서 이미 돌려 본 것을 가져오는 쪽으로 두 시간 만에 바꿨다. 그게 맞았는지는 월요일부터 보게 된다.

월요일부터는 preview.2를 회사 일에 붙이고, 개인 프로젝트와 회사 일 양쪽에서 기록을 모은다. 19편에서 배운 게 하나 있다. 고치려고 보니 근거가 될 기록부터 없었다는 것. 그래서 이번엔 붙이기 전에 무엇을 기록할지부터 정해 두려고 한다. 다음 글은 그 이야기다.


관련 글과 참고 자료: