1.0을 내고, 1분 만에 써 볼 수 있게 했다

2026.11.07 게시

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

1.0을 내고, 1분 만에 써 볼 수 있게 했다 — 명령 하나로 체험 환경을 만들면 READY가 나오고, 심어 둔 과제 셋 중 페이지 버그는 Small로 병합, 비밀번호 저장은 Large로 멈춘다

지난 글은 11월 1일에 써 두었다가 이 글과 함께 올린다. 그 글 끝에 직접 써 볼 사람이 있다면 이슈로 알려 달라고 적었다.

그 사이 방법론은 v1.0.0과 v1.0.1까지 나갔다. 이슈 목록은 조용했다. 방문 통계를 열어 보니 최근 2주 동안 들어온 사람은 네 명, 스타는 0개였다. 써 보고 말고 할 것도 없이 거의 아무도 보지 않았다.


1.0까지

10편에서 방법론을 프로젝트에 심으면 안 쓰는 사람에게도 딸려 간다고 적었다. 그런데 preview.7까지의 공개본은 설치하면 AGENTS.md에 방법론 구간이 생기고 프로젝트 안에 Skill이 깔렸다. 1.0에서는 새로 권장하는 적용 방식을 10편의 모양으로 바꿨다.

1.0의 구조. 제품 저장소에는 세 줄짜리 연결 파일 하나만 생기고, 그 파일이 팀이 소유하는 절차 저장소의 커밋을 가리킨다. 공개 방법론은 처음 복사해 가는 출발점이다. 작업에 골랐을 때만 절차를 읽는다

작업에 방법론을 골랐을 때만 읽기 전용 도구가 연결을 확인해 READY를 돌려준다. READY는 읽을 연결이 확인됐다는 뜻이지, Agent가 실제로 읽고 따랐다는 뜻은 아니다. 확인하지 못하면 다른 방법으로 넘어가지 않고 멈춘다. 예전 방식으로 설치한 프로젝트가 자동으로 바뀌지는 않는다.

다음 날 아침에 낸 1.0.1은 두 가지를 고쳤다. 일상적인 Trivial·Small 작업은 Skill 네 개를 다 읽는 대신 한 장짜리 절차를 따르게 했다. 그리고 보조 스크립트, 캐시, 컴파일 출력도 쓰기 범위에 넣었다. 앞선 시험에서 Agent가 허용된 경로 밖 OS 임시 폴더에 보조 파일을 만든 일이 있었기 때문이다.

이 판으로 다섯 언어(Python, JavaScript, TypeScript, Java, Go)에서 Small 작업을 Codex에게 하나씩 시켰다. 첫 시도는 셋만 끝났고, 환경 문제로 멈춘 둘은 고친 뒤 다시 돌려 다섯 모두 끝까지 갔다. 한 작업에 4분 반에서 6분 가까이 걸렸다. 조건이 이전 시험과 달라서 빨라졌다고 말할 수는 없다.


써 보기까지 너무 멀었다

실제로 누가 써 봤는지는 방문자 수만으로 알 수 없다. 다만 처음 온 사람의 눈으로 다시 보니 걸리는 곳이 두 군데 있었다.

  • 첫 화면. 등급 표가 먼저 나오고, 단서 조항과 검증 이력이 길게 이어졌다. 22편에서 고친 기준은 “따라오면 끝까지 갈 수 있는가”였지, “30초 안에 뭔지 알 수 있는가”가 아니었다.
  • 써 보는 데 드는 품. 1.0 구조대로 하려면 팀 절차 저장소를 만들고, 설정 문서 아홉 개를 채우고, 허용 목록을 쓰고, 기록 위치를 정해야 한다. 구경하러 온 사람이 할 일은 아니다.

첫 화면은 한 줄 소개(“오타와 마이그레이션을 구분하는 스펙 주도 개발”)와 흐름도, 빠른 시작, 설치 후 구조를 위로 올렸다. “효과는 재지 않았다”는 문장은 그대로 두고 지난 판들의 검사 기록만 접었다.


1분 체험

써 보는 품은 명령 하나로 줄였다.

git clone https://github.com/seok-jun/adaptive-agentic-sdd
python3 adaptive-agentic-sdd/try/setup.py

준비 스크립트는 Windows PC에서 5초쯤 걸렸다. 네트워크를 쓰지 않고, 만든 체험 폴더 안에만 쓴다. 그 안에 작은 Python 라이브러리, 이 라이브러리에 맞춘 팀 절차 저장소, 로컬 원격, 작업 기록 폴더가 생기고, 마지막에 READY까지 확인한다. 1.0 구조 한 벌이다. 그다음 START-HERE.md에 적힌 명령으로 Agent를 열고 과제 하나를 맡기면 된다. 1분이면 시작할 수 있고, 과제는 Agent가 몇 분 걸려 끝낸다.

심어 둔 과제 기대하는 등급
README의 깨진 링크 Trivial
페이지 나누기 함수가 한 칸씩 덜 돌려주는 버그 Small
회원 비밀번호 해싱과 저장 Large. 사람이 정할 것을 묻고 멈춰야 한다

스크립트는 Codex가 명세를 받아 만들었고, Claude Code가 실제로 돌려 보며 검토했다. 검토에서 고친 것 중 둘이 기억에 남는다. Codex 실행 명령이 원본 저장소까지 쓰기 가능하게 열고 있었고(Codex의 --add-dir은 쓰기 권한이다), Large 예제가 “묻고 멈춰라”라고 정답을 알려 주고 있었다. 정답을 알려 주면 Agent가 스스로 멈추는지 볼 수 없어서, 그냥 “비밀번호 해싱과 저장을 추가해 줘”로 바꿨다.


실제로 시켜 봤다

안내의 요청문을 그대로 쓰고 마지막 줄만 과제로 바꿨다. 아래는 Codex 실행 두 건의 실제 출력을 줄인 것이다.

체험 환경에서 실제 Codex 실행 두 건. 페이지 버그는 Small로 판정하고 실패하는 테스트 다섯 개를 먼저 확인한 뒤 고쳐 병합했다. 비밀번호 저장은 Large로 판정하고 제품 코드를 바꾸지 않은 채 사람이 정할 것을 물으며 멈췄다

실행 과제 결과
Codex, Windows 페이지 버그 Small. 실패하는 테스트를 먼저 확인하고 고쳐 병합, 작업 종료
Codex, Windows 비밀번호 저장 Large. 제품 파일을 하나도 바꾸지 않고 여섯 가지를 물으며 멈춤
Claude Code, macOS 페이지 버그 Small. 끝까지 감

몇 가지는 짚어 둔다.

  • Large 멈춤은 규칙을 따른 결과다. 예제의 권한 문서에 “비밀번호 저장은 사람이 정한다”고 적어 두었고, Codex도 그 문장을 근거로 들었다. Agent가 위험을 스스로 알아챘다고 보기는 어렵다.
  • Claude Code는 Git 버전에 걸렸다. 그 Mac의 Git 2.37에는 병합 가능 여부를 미리 보는 명령이 없었다. 방법론에 적힌 대체 절차(임시 폴더에서 시험 병합)로 넘어갔고, 실패한 병합 명령 하나는 다시 시도한 뒤 기록에 남겼다. 이 내용은 그 Agent의 보고를 근거로 적었다.
  • Codex 실행 조건은 최종 안내와 달랐다. 체험 폴더 최상위에서 시작해서 첫 시도는 시작부터 거부됐고, 원본 저장소에도 쓰기를 열어 둔 상태였다. 위에서 고친 그 설정이다. 실행 뒤 원본 저장소에 바뀐 것은 없었다.

지금 확인된 것과 아닌 것

  • 체험 환경: Windows와 macOS에서 영어·한국어 두 판 모두 READY, 테스트 123개 통과. Linux는 돌리지 않았다.
  • 실제 작업: 과제마다 한 번, 모두 영어판이다. 한국어판 작업, Trivial 과제, Claude Code의 Large 과제는 돌리지 않았다.
  • 쓰기 범위: Agent가 지시한 쓰기는 체험 폴더 안이었다. Claude Code 실행에서는 호스트가 큰 출력을 자기 세션 폴더에 저장한 예외가 있었다. 호스트 샌드박스가 바깥 쓰기를 실제로 막았는지는 시험하지 않았다.
  • 효과: 여전히 재지 않았다.

자세한 조건과 한계는 체험 환경 실행 기록에 있다.


정리

한 것 결과
1.0 방법론을 프로젝트 밖에 두고, 고른 작업에서만 읽게 했다
1.0.1 일상 작업을 짧게 하고, 임시 파일도 작업 범위에 넣었다
첫 화면 한 줄 소개, 흐름도, 빠른 시작, 설치 후 구조를 위로
1분 체험 명령 하나로 1.0 구조 한 벌. Windows·macOS 확인
실제 실행 Small은 두 Agent 모두 끝까지, Large는 규칙대로 멈춤
효과 재지 않았다

22편에서는 README를 따라오는 Agent가 어디서 멈추는지 봤다. 이번에는 처음 온 사람이 시작하기까지의 과정을 봤다. 실제로 어디서 멈췄는지는 모른다. 다만 구경 삼아 시작하기에는 준비할 것이 너무 많았고, 그걸 명령 하나로 줄였다.

다음 주에는 처음으로 저장소 바깥에 알려 볼 생각이다. 써 보다 막힌 곳이 있으면 이슈로 알려 주면 좋겠다. 어느 단계였는지, 어떤 Agent와 OS였는지를 같이 적어 주면 바로 고칠 수 있다.


관련 글과 참고 자료: