드디어 방법론 분리 진행
2026.10.16 게시
이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.
![]()
10편에서 방법론을 프로젝트 밖에 두고 싶다고 썼다. 12편에서는 모델이 바뀔 때마다 프로젝트를 같이 뜯지 않으려면 빼야 한다고 했다. 14편 끝에서 다음에 그 얘기를 하겠다고 해 놓고, 15편에서 한 번 미뤘다.
이번 글이 그 얘기다.
미리 말하면 계획한 대로 깔끔하게 나뉘지는 않았다. 버전만 적어 두는 연결을 만들었는데 앱은 그걸 쓰지 않았다. 분리하기 전에 먼저 이어 봤는데, 그 연결이 시험이 끝나도 남아서 다시 풀어야 했다.
전체 흐름은 이렇다.
그림에 나오는 이름이 많아서 먼저 정리해 둔다.
| 이름 | 뜻 |
|---|---|
| Agent 작업 규칙 | Agent에게 일을 시킬 때 따르게 하는 문서들. 작업을 크기별로 나누는 기준, 리뷰 방식, 끝날 때 남길 기록 같은 것 |
| 앱 저장소 | 실제로 만들고 있는 안드로이드 앱. 17편에서 “실무 프로젝트”라고 부른 곳이다 |
| 연구 저장소 | 차세대 규칙을 설계하고 실험하는 곳. 13~16편의 실험도 여기서 했다 |
| 앱 전용 규칙 저장소 | 이 앱이 실제로 쓰는 규칙을 따로 담아 둔 저장소 |
왜 빼려고 했나
규칙이 앱 저장소 안에 들어 있으면 둘이 같이 움직인다.
17편에서 센 산문 약 253KB가 전부 앱 저장소 안에 있었다. 규칙을 고치는 이슈도 앱 기능 이슈 사이에 섞여 쌓였다. 규칙 문장 하나를 바꾸려고 열어 보면 모듈 경계, 빌드 설정, 앱 전용 검사 도구가 같이 걸려 있어서 그것까지 다시 봐야 했다.
모델은 몇 달마다 바뀌는데, 그때마다 앱 저장소를 같이 뜯을 수는 없었다. 다른 프로젝트에서 같은 규칙을 쓰려면 통째로 복사해서 다시 고쳐야 하는 것도 문제였다.
그래서 규칙은 밖에 두고, 앱에는 “어떤 규칙의 어떤 버전을 쓴다”는 정보만 남기기로 했다.
계획: 라이브러리처럼 버전만 적는다 (10/02)
자바 개발자라면 익숙한 방식을 그대로 가져왔다. 라이브러리를 프로젝트에 넣을 때 소스를 복사하지 않고 pom.xml에 버전만 적는 것처럼.
| 라이브러리 | Agent 작업 규칙 | |
|---|---|---|
| 앱에 적는 것 | pom.xml에 버전 |
연결 파일 하나에 규칙 버전 |
| 내용이 바뀌면 | 버전이 바뀐다 | 문서 내용의 해시가 바뀌어 버전이 바뀐다 |
| 버전이 안 맞으면 | 빌드 실패 | 최신판으로 대신하지 않고 멈춘다 |
규칙 문서 세 개를 하나로 묶고, 세 문서의 해시로 버전을 만들었다. 앱 쪽에는 연결 파일 하나만 생기고, 앱이 원래 갖고 있던 규칙 파일은 건드리지 않는다. 규칙 버전을 바꾸는 일과 앱 규칙을 바꾸는 일이 서로 엮이지 않게 하려는 거다.
연결 파일을 설치하고, 갱신하고, 되돌리고, 지우는 도구도 만들었다. 이 도구는 Windows·macOS·Linux에서 같은 검사 60개를 통과했다. 사용자가 고친 파일을 덮어쓰지 않는지, 설치 도중에 프로세스가 죽어도 파일이 반쯤 쓰인 채로 남지 않는지 같은 것들이다.
여기서 문제가 하나 발견됐다. 줄바꿈이었다. Windows에서 검사를 돌렸더니 결과는 다 통과인데 소스 해시가 macOS와 달랐다. 받아 둔 파일 두 개에 Windows식 줄바꿈(CRLF)이 남아 있었다. 내용으로 버전을 만드는 방식이라 줄바꿈 하나도 다른 버전이 된다.
다만 이 60개는 연결 파일을 다루는 도구의 검사다. Agent가 읽은 규칙을 잘 따르는지와는 상관이 없다.
그런데 앱은 그 도구를 쓰지 않았다
바로 분리하지는 않았다. 차세대 규칙을 앱에 정식으로 옮기기 전에, 이 계획이 실제 작업에서 맞게 돌아가는지부터 보고 싶었다.
그래서 10월 9일부터는 앱이 연구 저장소의 특정 커밋을 직접 읽게 이어 두고 실제 작업을 돌리며 데이터를 모았다. 앱의 작업 절차 문서 안에 연구 저장소의 커밋과 해시를 적어 두고 규칙 세 문서를 읽게 했다. 승인 확인 도구도 연구 저장소의 특정 커밋에 있는 실행 파일을 그대로 돌렸다.
라이브러리로 치면 정식 배포 전에 개발 브랜치를 의존성으로 걸어 놓고 써 보는 단계다.
10월 10일에 이렇게 이어 둔 상태로 실제 작업 하나를 처음부터 끝까지 따라가 봤다. 연결이 들어간 뒤 시작된 큰 기능 작업 한 건이었고, 중간에 끼어들지 않고 남은 기록만 읽었다.
두 가지를 알게 됐다.
첫째, 세 OS에서 검사까지 마친 연결 파일과 도구는 앱이 실제로 쓰는 길이 아니었다. 앱은 문서 안에 적어 둔 커밋과 해시로 규칙을 읽고 있었다. 60개 검사가 증명한 건 앱이 쓰지 않는 길이었던 셈이다.
둘째, 차세대 규칙이 실제로 읽히는 곳은 네 군데뿐이었다.
| 작업 단계 | 누구 규칙이 맡았나 |
|---|---|
| 이슈 접수, 작업 크기 판정, 설계 | 원래 앱 규칙 |
| 리뷰, 사람 승인, 검증 | 원래 앱 규칙 |
| 변경 전 기록, 인계, 구현 종료 요약, 정리 전 재조회 | 차세대 규칙 |
| 마무리와 정리 절차 | 원래 앱 규칙 |
기존 규칙을 갈아 끼운 게 아니라, 위에 기록하는 층 하나를 덧붙인 상태였다.
이걸 보고 목표를 다시 잡았다. 처음엔 “기존 방법론을 차세대로 전부 교체한다”를 목표로 삼았는데, 무엇을 교체해야 다 바꾼 건지부터가 정해져 있지 않았다. 그래서 기준을 “공통이 가진 것과 프로젝트가 가진 것이 구별되고, 각자 자기 자리에서 읽히는가”로 바꿨다.
공통 쪽에는 지금 검증된 것만 남겼다. 작업 기록을 근거로 규칙을 고치는 틀, 승인 확인 도구, 검토 문서 서식 정도다. 나머지는 프로젝트가 갖는다. 일부러 얇게 뒀다.
질문이 “규칙을 어디에 두나”에서 “어떤 규칙을 누가 갖나”로 바뀐 셈이다.
다시 분리: 시험 연결이 남긴 얽힘 (10/15~)
10월 15일에 본격적으로 나눴다.
먼저 앱 저장소 안의 Agent 절차를 앱 전용 규칙 저장소로 옮겼다. 기준은 단순했다. 항상 지켜야 하는 것과 앱에 대한 사실은 앱에 남기고, 작업할 때 골라서 쓰는 절차는 밖으로 뺐다.
| 앱 저장소에 남긴 것 | 앱 전용 규칙 저장소로 옮긴 것 |
|---|---|
| 대화·비밀 기록 금지, 모듈 경계, 꼭 돌려야 하는 검증 | 작업 크기별 설계 절차, 리뷰 방식 |
| Agent 도구마다 붙는 얇은 입구 | 시작·종료 기록 방식, 실제 규칙 원본 |
옮긴 절차도 여전히 앱 소유다. 위치만 바뀌었고, 앱이 정한 리뷰나 필수 검증을 빼거나 약하게 하지 않았다. 같은 날 사람 서명 승인도 뺐는데, 그건 다음 글에서 적는다.
그런데 옮기고 나서 보니, 떼어 낸 규칙 저장소가 또 연구 저장소에 묶여 있었다. 시험 연결 동안 생긴 얽힘이 그대로 따라온 거다.
| 얽힌 것 | 그대로 두면 |
|---|---|
| 규칙 저장소의 버전 고정 파일이 연구 저장소 파일들을 해시로 고정했는데, 그중 하나는 규칙이 아니라 설계 검토 문서였다 | 실험용 메모가 앱의 실행 규칙이 된다 |
| 앱 CI가 연구 저장소를 내려받았다 | 연구 저장소를 고치면 앱 CI가 흔들린다 |
| 앱의 작업 경과와 전환 준비 문서가 연구 저장소에 쌓였다 | 연구 기록과 앱 기록이 섞인다 |
그래서 연구 저장소는 어떤 프로젝트와도 직접 이어지면 안 된다고 판단했다. 같은 날 앱과 규칙 저장소에서 연구 저장소 의존을 걷어 냈다. 버전 고정 파일과 CI가 내려받는 대상을 모두 규칙 저장소로 바꿨다.
다음 날 다시 확인해 보니, 두 저장소 전체 파일에서 연구 저장소 이름이 남은 곳은 한 군데였다. 연구 저장소를 원본으로 쓰지 못하게 막는 테스트였다. 연구 저장소 쪽에도 “어떤 프로젝트도 여기를 실행 원본으로 직접 읽지 않는다”고 적어 두었다.
이제 앱은 규칙 저장소의 커밋과 해시를 고정해서 읽는다. 맞지 않으면 최신판으로 대신하지 않고 멈춘다. 처음 계획한 “버전만 적어 둔다”에 겨우 가까워졌다.
앱 쪽에 남은 고정 파일은 지금 이렇게 생겼다. 저장소 이름은 글에서 쓰는 이름으로 바꾸고, 긴 해시와 반복 항목은 줄였다.
{
"schema_version": 1,
"repository": "<앱 전용 규칙 저장소>",
"commit": "0bb32050dd42…",
"manifest": { "path": "manifest.json", "sha256": "30665649…" },
"common_lock": { "path": "references/common.lock.json", "sha256": "413d359c…" },
"product_text_transport": "utf8-lf-v1",
"managed_files": {
".agents/skills/finishing-issues/SKILL.md": "d0b02c8c…",
".claude/skills/finishing-issues/SKILL.md": "573386ec…",
"tools/workflow_connection.py": "2dcff31e…"
}
}
pom.xml에 버전 한 줄을 적는 것보다는 길다. 규칙 저장소의 commit 하나, 그 안의 목록 파일 두 개의 해시, 그리고 앱에 실제로 복사돼 있는 Skill·도구 파일의 해시를 같이 고정한다. product_text_transport는 위에서 말한 줄바꿈 문제 때문에 생긴 항목이다. 내용을 LF 바이트로 맞춘 뒤에 해시를 잰다는 뜻이다.
재미있는 건, 확인해 보니 연구 저장소의 규칙과 앱 쪽 사본이 벌써 파일 하나가 달랐다는 거다. 동기화가 깨진 게 아니라 각자 갖게 되면서 생긴 차이다. 앞으로 연구 저장소에서 고친 걸 앱 쪽 사본으로 옮기려면 따로 변경을 해야 한다. 이게 분리의 비용이다.
참고로 이 블로그 저장소도 공통 이슈 분류 기준은 같은 규칙 저장소의 고정 커밋에서 읽는다.
회피한 문제, 발견된 문제
분리하면서 앱 쪽에도 규칙 저장소를 읽어 오는 연결 도구가 생겼다. 그런데 10월 2일과 비슷한 문제가 다시 나왔다.
| 문제 | 10/02 연구 저장소 도구 | 10/15~16 앱 쪽 연결 도구 |
|---|---|---|
| 같은 함수, OS마다 다른 동작 | os.rename: 설계 때 알고 회피 |
os.execv: 실제로 발견 |
| 줄바꿈 | 발견: CRLF 때문에 소스 해시가 다름 | 발견: 같은 이유로 버전 해시가 또 다름 |
10월 2일의 os.rename은 대상 파일이 이미 있을 때 OS마다 동작이 다르다(Python 문서). Windows에서는 실패하지만 다른 OS에서는 기존 파일을 조용히 덮어쓴다. 설계할 때 이걸 알고 있어서, OS마다 덮어쓰지 않는 방식을 따로 골라 회피했다.
execv는 미리 알지 못했고, 실제로 문제가 발견됐다. 이 도구는 격리 옵션 없이 실행되면, 그 옵션을 붙여 자기 자신을 다시 실행한다. Linux나 macOS에서는 execv가 현재 프로세스를 새 프로세스로 바꾸니 결과 코드가 그대로 전달된다. 그런데 Windows에서는 새 프로세스를 띄우고 원래 프로세스는 바로 성공(0)으로 끝나 버린다(Python 문서).
문제가 된 건 Skill 문서에 적힌 호출 형태 그대로 실행한 경우였다. 그래서 주로 쓰는 Windows에서 “버전 검증에 실패하면 멈춘다”는 조건이 동작하지 않았다. 검증이 실패해도 성공으로 기록될 수 있는 상태였다.
이슈에 적어 둔 재현 결과는 이랬다.
| Windows에서, 문서에 적힌 호출 형태로 | 그때 | 기대 |
|---|---|---|
resolve에 없는 항목을 지정 |
exit 0, 출력 없음 | BLOCKED 출력 뒤 exit 1 |
verify 정상 실행 |
0.07초 만에 exit 0, 결과 JSON은 20~35초 뒤에 따로 도착 | 출력이 끝난 뒤 exit 0 |
이 글을 올린 날 오전에 고쳤다. 고친 부분은 이렇다.
_bootstrap_os=sys.modules.get('os')
if _bootstrap_os is None: raise RuntimeError('isolated product bootstrap unavailable')
- _bootstrap_os.execv(sys.executable,[sys.executable,'-I','-B',*sys.argv])
+ _bootstrap_argv=[sys.executable,'-I','-B',*sys.argv]
+ if _bootstrap_os.name=='nt':
+ # spawnv uses the Windows CRT command line, not an argv array. Quote
+ # every argument, doubling backslashes before quotes and at the end.
+ def _bootstrap_quote(argument):
+ ...
+ raise SystemExit(_bootstrap_os.spawnv(_bootstrap_os.P_WAIT,sys.executable,
+ [_bootstrap_quote(argument) for argument in _bootstrap_argv]))
+ _bootstrap_os.execv(sys.executable,_bootstrap_argv)
Windows에서만 spawnv(P_WAIT, …)로 자식 프로세스가 끝날 때까지 기다리고, 자식의 종료 코드를 그대로 돌려준다. POSIX 쪽은 원래대로 execv다. 한 줄 고치는 문제처럼 보였는데, spawnv는 인자를 배열이 아니라 Windows 명령줄 문자열로 넘기기 때문에 따옴표와 역슬래시 처리를 따로 넣어야 했다. 같은 부트스트랩이 도구 네 개에 들어 있어서 넷 다 고쳤다.
정리
시험으로 이어 둔 연결은 시험이 끝나도 남는다. 분리는 결국 그 연결을 하나씩 찾아서 끊는 일이었다.
공들여 만든 연결 도구를 앱이 안 쓰고 있었다는 것도 직접 따라가 보기 전엔 몰랐다. 검사를 다 통과했다고 그게 실제로 쓰이는 길이라는 뜻은 아니었다. 17편에서 “검사는 통과했지만 요구를 증명하지 못한” 사례를 세었는데, 내 쪽에서도 같은 모양이 나왔다.
그럼 60개 검사는 헛수고였을까. 지금도 필요한지는 솔직히 의문이다. 검사를 받은 연결 도구는 앞으로 쓰일 일이 없다.
그래도 OS를 확인하는 일 자체는 계속 필요하다고 생각한다. 방법론은 한 OS에서만 쓰이지 않는다. 이번 execv 문제도 도구 안쪽만의 문제가 아니었다. Skill 문서에 적힌 명령이 특정 OS에서만 의도대로 동작했다. 그러니 앞으로 볼 건 연결 파일 검사 60개보다, 워크플로 문서와 Skill, Hook에 한 OS에 묶인 문구나 명령이 있는지다.
그리고 바로 분리하지 않고 먼저 이어 본 덕에 알게 된 것도 있다. 차세대 규칙이 실제로 쓰이는 곳이 시작·인계·종료 기록뿐이라는 걸 알고 나서야, 무엇을 공통에 두고 무엇을 앱에 둘지 나눌 수 있었다.
아직 못 한 것도 있다.
- Agent가 읽은 규칙을 실제로 따르는지는 이번 분리와 상관없이 여전히 모른다.
- 연구 저장소에서 고친 걸 앱 쪽 사본으로 언제, 어떻게 옮길지는 정하지 않았다.
- 워크플로·Skill·Hook에서 한 OS에 묶인 부분을 어떻게 찾을지 정하지 않았다.
다음 글은 시험 연결 동안 남긴 시작·종료 기록을 근거로 Agent가 규칙을 직접 고치게 해 본 이야기다.
관련 글과 참고 자료: