코드보다 먼저 바꿔야 할 개발 프로세스 intent.md, AI-Native SDLC Playbook 분석

앤트로픽이 8월 21일에 The AI-Native SDLC Playbook 이라는 글을 올렸습니다. 같은 이름으로 Claude Academy 에 무료 코스도 열렸는데, 차시 제목이 글 소제목이랑 거의 같아서 글부터 읽었습니다.

읽게 된 이유는 단순합니다. 제가 그동안 만들어 온 것들이 글에 나오는 파일 이름들이랑 많이 비슷했습니다. CLAUDE.md 가 있고, 스킬이 있고, 커밋 직전에 도는 훅이 있고, 서브에이전트를 정의해 둔 폴더가 있습니다. 그때그때 필요해서 하나씩 쌓아 올린 걸 누가 이름을 붙여 정리해 놓은 문서일지도 모르겠다 싶었습니다. 읽어 보니 절반은 그랬고, 나머지 절반은 제가 이미 해 봤다가 실패한 방식이었습니다.

코드가 더 이상 병목이 아니라는 이야기

문서는 "Code is no longer the bottleneck" 이라는 말로 시작합니다. 코드는 1년 전에는 상상하기 어려운 속도로 나오는데, 코드 주변의 프로세스는 그 속도로 바뀌지 않았다는 겁니다. 승인 게이트, 리뷰, 핸드오프, 정책이 예전 그대로 남아서 늘어난 생산성을 도로 잡아먹고 있다고 적었습니다.

여기까지는 많이 들어 본 말인데 그다음 문장이 저한테는 제일 크게 남았습니다. 전통적인 SDLC 는 코드를 쓰고 구현하는 단계가 가장 오래 걸리고 가장 비쌌던 시대에 맞춰 효율을 끌어올리도록 만들어진 것이고, 이제 그게 사실이 아니라는 겁니다. 프로세스가 낡았다는 말과는 좀 다르게 들렸습니다. 프로세스가 아끼려고 했던 대상이 없어졌다는 말에 가깝습니다.

리뷰를 몇 번 거치고, 누가 승인하고, 어느 단계에서 다음 팀으로 넘기는지가 전부 "코드 쓰는 시간은 비싸니까 잘못 쓰지 않게 앞에서 막자" 는 생각에서 나왔다고 보면, 코드 쓰는 시간이 싸진 지금은 그 장치들이 무엇을 지키고 있었는지부터 다시 봐야 합니다. 비싼 걸 아끼려고 만든 절차가 이제 그 자체로 제일 비싼 단계가 돼 있는 셈입니다. 그럼 어디를 아껴야 하느냐는 질문이 남고, 문서의 나머지 여섯 단계가 거기에 대한 앤트로픽 쪽의 답입니다.

Plan 단계는 백로그 대신 intent.md 한 장

예전에는 아이디어 하나가 백로그 항목, 유저 스토리, 스토리 포인트, 리파인먼트 미팅을 다 거친 다음에야 누군가 손을 댈 수 있었다고 적혀 있습니다. 이제는 아이디어를 낸 사람이 클로드와 이야기를 나누고 그 결과를 intent.md 로 적습니다. 문서는 이걸 "a proto-spec in the originator's own terms" 라고 부릅니다. 제안한 사람이 자기 말로 쓴 초기 스펙이라는 뜻이고, 무엇을 원하는지, 왜 원하는지, 어떤 제약 아래에서인지를 담습니다. 프로덕트 오너가 에이전트가 쓴 intent.md 를 검토하고 고쳐서 커밋하고, 받아들였는지 거부했는지는 머지나 리뷰 종료로 기록에 남습니다.

여섯 단계 중에 이게 제일 저항이 적을 것 같습니다. 백로그 항목 쓰는 걸 즐거워하는 사람은 별로 못 봤고, 그렇게 쓴 문서를 나중에 누가 다시 읽는 일도 드뭅니다. 다만 이 단계가 잘 되는 조직은 아마 그 전에도 잘 됐을 것 같습니다. 제안한 사람이 자기가 원하는 걸 자기 말로 적을 수 있어야 시작이 되는데, 원래 그게 안 되던 조직이라면 intent.md 도 리파인먼트 미팅에서 받아 적은 문서가 될 겁니다. 파일 이름만 바뀌는 거죠. 자기 말로 쓴다는 조건이 이 단계의 전부인데, 그건 도구가 대신해 줄 수 있는 일이 아니라서 문서도 거기까지는 말하지 않습니다.

클로드와 이야기를 나누면서 쓴다는 것도 조금 생각해 볼 부분입니다. 혼자 쓰면 안 나오던 문장이 대화를 하면 나오기는 하는데, 그렇게 나온 문장이 정말 그 사람 말인지 클로드 말인지는 쓴 사람도 헷갈릴 것 같습니다. 문서가 굳이 "in the originator's own terms" 를 붙여 둔 게 그걸 알고 있어서일 수도 있겠다 싶었습니다.

만약 제가 이 블로그 글 하나를 시작할 때마다 intent.md 를 쓴다면 어떨까 생각해 봤습니다. 무엇을 쓰고 싶은지, 왜 쓰고 싶은지, 어떤 제약이 있는지. 막상 적으려고 하면 두 번째 칸이 제일 안 채워질 것 같습니다. 무엇을 하고 싶은지는 대개 금방 나오는데 왜 하고 싶은지는 하다 보면 생기는 경우가 많으니까요. 그 칸을 억지로 채우면 그럴듯한 이유가 나오긴 할 텐데, 그건 제 이유라기보다 문서를 완성하려고 만든 이유일 겁니다. 이 단계가 조직에서 실제로 쓰이면 아마 그 칸이 제일 먼저 형식이 될 것 같습니다.

Design 단계는 요구사항과 설계를 한 세션에

요구사항과 설계를 다른 팀이 다른 단계에서 하는 이유를 문서는 책임 소재 때문이라고 인정합니다. 그러면서도 느리고, 넘기는 과정에서 빠지는 게 많다고 적었습니다. 분리한 목적은 건드리지 않고 비용만 짚는 방식이라 읽는 쪽에서 반박하기가 어렵습니다.

그래서 둘을 한 번의 세션에 넣습니다. 클로드가 intent.md 를 받아 요구사항과 설계 스펙을 만들고 걱정되는 부분에 표시를 남기면, 프로덕트 오너가 승인하고, 조직이 고위험으로 분류한 건 테크 리드나 아키텍트에게 갑니다. 회사마다 다른 설계 관행은 조직 단위 스킬에 넣어서 이 세션을 안내하게 합니다.

읽는 내내 책임 문제가 걸렸습니다. 책임 소재 때문에 나눴던 걸 합쳤으니, 합친 다음의 책임은 승인하는 사람 한 명에게 몰립니다. 문서는 그 사람을 프로덕트 오너로 적었는데, 요구사항은 프로덕트 오너 일이 맞아도 설계가 맞는지까지 같은 사람이 판단할 수 있는지는 잘 모르겠습니다. 고위험이면 테크 리드가 본다고 했지만, 뭘 고위험으로 볼지도 누군가 정해야 하고, 그게 같은 사람이면 처음 질문으로 돌아옵니다. 이 단계가 실제로 빨라지는지는 회사마다 많이 다를 것 같습니다. 넘기는 횟수가 줄어드는 대신 한 사람이 들고 있는 무게가 커지는 건데, 그 무게를 그 사람이 감당할 수 있는지는 문서가 다루는 범위 밖에 있습니다. 저라면 프로덕트 오너가 설계 스펙을 승인하는 장면이 실제로 어떤 모습일지가 제일 궁금할 것 같습니다.

혼자 일하는 사람한테는 이 단계가 오히려 자연스럽습니다. 요구사항을 정하는 사람도 설계를 승인하는 사람도 어차피 한 명이니까요. 조직이 나눠 놨던 걸 합치는 게 이 단계의 요지라면, 1인 개발자는 처음부터 합쳐진 상태로 일해 온 셈입니다. 그렇게 보면 이 문서가 그리는 조직은 큰 회사가 혼자 일하는 사람처럼 일하게 만드는 쪽에 가까운 것 같기도 합니다.

Build 단계는 계획을 먼저 쓰는 데서 시작합니다

예전에는 엔지니어가 설계를 읽고 바로 코드를 쓰기 시작했고, 어떻게 바꿀지는 그 사람 머릿속에만 있었다고 적혀 있습니다. 문서 표현으로는 "stays in the engineer's head" 입니다. 이제는 클로드가 plan mode 에서 계획을 먼저 써서 plan.md 로 남깁니다. 바뀌는 파일, 작업 순서, 그걸 증명할 테스트를 담습니다. 그리고 한 줄이 더 붙어 있습니다.

When implementation departs from the plan, update plan.md in the same commit

나머지는 이미 익숙한 것들입니다. CLAUDE.md 에는 코드베이스 관행과 자주 하는 실수를 적고, 스킬로는 조직 정책을 일관되게 적용합니다. 문서는 스킬을 "institutional knowledge" 라고 부르는데, 사람이 나가면 같이 사라지던 걸 파일로 남겨 두자는 뜻으로 읽었습니다. 사람이 나가면 사라지던 지식이라는 게 대부분 "이건 이렇게 하면 안 된다" 같은 종류라는 걸 생각하면, 스킬 파일에 적히는 것도 결국 금지 목록에 가까워질 것 같습니다. 그런 목록은 쓰기는 쉬운데 언제 지워야 하는지는 아무도 모릅니다.

엔지니어 한 명이 세션 여러 개를 동시에 띄우고, 세션마다 자기 워크트리에서 자기 과제를 맡게 합니다. 반복되는 일은 .claude/agents/ 아래 마크다운으로 서브에이전트를 정의해서 떼어 냅니다. 언제 부를지와 어떤 도구를 쓸지를 거기 적어 둡니다. 코드를 단순화하는 역할, 동작을 테스트로 확인하는 역할, 코드베이스를 뒤지는 역할 같은 예가 나옵니다.

병렬 세션은 두세 개로 시작하라고 하고, 실제 상한은 리뷰 능력이 정한다고 적었습니다. 이 대목은 반가웠습니다. 세션을 여덟 개 띄워 놓고 결과를 다 못 읽으면 그건 여덟 배 일한 게 아니라 일곱 개를 안 보고 넘긴 거라고 생각합니다. 띄운 세션 개수를 성과처럼 세기 시작하면 그 숫자는 얼마든지 늘어나는데 읽는 사람의 시간은 안 늘어납니다. 그 차이를 문서가 먼저 적어 둔 게 좋았습니다.

리뷰 능력이 상한이라는 말을 조금 더 밀어 보면, 결국 이 단계에서 늘어나는 건 엔지니어의 손이 아니라 눈이 해야 할 일입니다. 손으로 하던 일을 세션에 넘기면 그만큼 눈으로 볼 게 쌓입니다. 그럼 리뷰 능력을 어떻게 늘리느냐가 다음 질문이 되는데, 문서는 그걸 서브에이전트에게 일부 넘기는 쪽으로 답하는 것 같습니다. 단순화하는 역할, 테스트로 확인하는 역할이 그런 일을 하겠죠. 그런데 그 서브에이전트가 본 걸 또 누군가는 봐야 합니다. 보는 일을 넘길수록 보는 사람이 보는 대상이 코드에서 코드를 본 결과로 한 칸씩 멀어집니다. 몇 칸까지 멀어져도 괜찮은지는 잘 모르겠습니다.

Test 단계에서 설정 자체를 시험합니다

예전 방식을 적은 문장이 좀 아팠습니다. 코드가 돈다는 신호가 늦게 도착한다는 겁니다. CI 는 몇 분 뒤, 테스터는 며칠 뒤, 프로덕션은 몇 주 뒤에 옵니다. 이제는 사람이 보기 전에 세션이 자기 작업을 스스로 확인할 방법을 줍니다. 테스트를 돌리거나 스크린샷을 찍게 해서, 자기 실수를 자기가 고친 다음에 사람 앞에 오게 하는 겁니다.

버그 수정에는 조건이 하나 더 있습니다. 실패하는 테스트를 사람이 먼저 쓰고, 고치는 동안 에이전트가 그 테스트를 못 건드리게 합니다. 그래야 버그가 진짜 없어졌다는 게 증명된다는 거죠. 이건 게이트가 됩니다. 테스트 파일이 바뀌었는지 안 바뀌었는지는 모델이 뭐라고 하든 이미 정해져 있는 사실이니까요. 사람이 먼저 쓴다는 조건이 핵심처럼 보였습니다. 에이전트가 테스트와 수정을 한꺼번에 쓰면, 둘이 서로를 맞춰 주기만 해도 초록불이 들어옵니다. 그건 버그가 없어진 게 아니라 테스트가 버그를 따라간 겁니다.

그리고 CI 에서 도는 평가셋이 있습니다. 문서는 continuous evals 라고 부릅니다. 여기서 평가하는 대상이 코드가 아니라 CLAUDE.md 와 스킬과 훅, 그러니까 에이전트 설정 그 자체입니다. 결과가 알려진 실제 과제 스무 개에서 쉰 개 정도에 설정을 던져 봅니다.

The suite runs non-interactive in CI on a schedule and on any change to CLAUDE.md, skills or hooks.

정해진 주기마다, 그리고 설정 파일이 바뀔 때마다 돌립니다. 통과율이 떨어지면 설정 변경을 막고, 프로덕션에서 터진 사고는 영구 회귀 테스트로 넣습니다.

문서에서 이게 제일 새로웠습니다. 저는 제 CLAUDE.md 를 몇 번이나 고쳤는데, 고친 게 나아졌는지 나빠졌는지 확인해 본 적이 한 번도 없습니다. 고치고 나서 다음 세션이 별 문제 없이 돌면 잘 고쳤다고 여겼습니다. 확인했다기보다 그런 느낌을 받았던 겁니다. 프롬프트에도 회귀 테스트를 붙일 수 있다는 건 머리로는 알았는데 제 설정 파일에 그걸 해 볼 생각은 못 했습니다. 설정은 제가 쓰는 거고 코드는 모델이 쓰는 거라고 속으로 나눠 놓고, 제가 쓴 쪽은 시험할 대상에서 빼 두고 있었던 것 같습니다.

설정을 시험한다는 게 막상 해 보려면 어디서부터 해야 할지 막막하기도 합니다. 결과가 알려진 과제라는 조건이 제일 어렵습니다. 코드라면 테스트가 통과하느냐로 결과를 정할 수 있는데, 글을 쓰는 하네스라면 무엇이 맞는 결과인지부터 정해야 합니다. 이 글이 잘 쓴 글인지를 매번 같은 답이 나오는 방법으로 판정할 수 있을까 생각해 보면 잘 안 될 것 같습니다. 분량이나 금지어처럼 셀 수 있는 것만 평가셋에 들어가고, 정작 고치고 싶었던 문체는 빠질 겁니다. 그러면 평가셋은 통과하는데 글은 나아지지 않는 상태가 될 수도 있겠다 싶습니다.

Deploy 단계는 훅이 멈춰 세우고 사람이 통과시킵니다

지금 모습은 사람이 모든 줄을 읽고, 거버넌스는 리뷰 주기 안에서만 일어나고, 그것도 일관성이 없을 때가 많다고 적혀 있습니다. 문서는 에이전트 리뷰를 여러 단계로 두고, 사람 리뷰는 규제 대상이나 중요한 코드에만 남기라고 합니다.

이 단계는 꽤 조심스럽게 썼습니다. 훅을 승인 게이트로 쓰는데, 훅이 특정한 사람이 승인할 때까지 동작을 멈춰 세울 수 있습니다. 허용 목록에는 make build 같은 안전한 명령만 두고, 자격증명 접근이나 아무 데로나 나가는 네트워크 호출은 거부합니다. 샌드박스는 OS 수준에서 격리하고 도메인을 제한합니다.

CI/CD 에는 처음에 비대화형 읽기 전용 작업으로만 넣고, 쓰기는 기존 승인 게이트 뒤에서만 허용합니다. 에이전트 작업은 네트워크 정책이 걸린 컨테이너 안에서, 수명이 짧고 범위가 좁은 토큰으로 돌고, 기본으로는 프로덕션 자격증명을 갖지 않습니다.

이 단계를 읽으면 문서가 에이전트를 얼마나 안 믿는지가 보입니다. 앞 단계에서는 계획도 쓰고 설계도 쓰라고 일을 잔뜩 맡기다가, 배포 앞에서는 토큰 수명까지 짧게 자릅니다. 저는 그 태도가 맞다고 봅니다. 맡기는 일이 많아질수록 끝에서 막는 장치는 더 단단해야 하니까요.

다만 끝에서 막는 장치가 단단할수록 앞 단계가 느슨해져도 괜찮다고 느끼게 될 것 같기도 합니다. 어차피 배포 앞에서 걸릴 테니 계획이나 설계는 대충 넘겨도 된다는 생각이 들기 쉽습니다. 문서가 단계마다 파일을 남기게 한 건 아마 그걸 막으려는 거겠지만, 파일이 남는 것과 그 파일을 누가 제대로 읽는 것은 또 다른 얘기입니다. 끝에서 다 막아 주겠지 하는 마음은 사람한테도 생기고, 아마 에이전트에게 일을 맡기는 사람한테는 더 쉽게 생길 것 같습니다. 결과가 너무 빨리 나오니까 중간을 볼 이유를 잘 못 느끼게 됩니다.

직무 분리는 분명하게 적어 놨습니다.

Separation of duties is preserved, because the agent that wrote the code has no way to approve it... Approval comes from a human through branch protection

코드를 쓴 에이전트에게는 그 코드를 승인할 방법이 아예 없고, 승인은 branch protection 을 거쳐 사람이 합니다.

Maintain 단계에서 탐지에는 모델을 넣지 않습니다

마지막 단계에서 한 바퀴가 닫힙니다. 예전에는 티켓이든 장애든 사람이 손대기를 기다렸는데, 이제는 관리 한계를 넘었다는 신호 같은 트리거가 사람 없이 클로드를 부릅니다.

보안 스캔은 이벤트가 생길 때마다 돌리던 걸 정해진 주기로 돌립니다. 연결된 저장소 전부를 대상으로, 쓸 수 있는 가장 강한 모델로 돌리고, 사람이 읽기 전에 탐지 결과를 먼저 검증해서 신뢰도 등급을 붙입니다. 스캐너 결과를 그대로 사람한테 넘기면 사람이 오탐 거르는 일을 하게 되는데, 그 일을 사람 앞에 오기 전에 끝내 두겠다는 겁니다.

프로덕션 모니터링 쪽이 제일 단호합니다.

Detection stays entirely deterministic, with no model involved.

탐지는 이동 기준선과 통계 규칙으로만 하고, Western Electric 규칙을 이름까지 들었습니다. 모델은 탐지가 끝난 다음에 들어옵니다. 1σ 를 벗어나면 로그만 남기고, 2σ 면 클로드가 읽기 전용으로 진단하고, 3σ 면 클로드가 PR 을 열거나 미리 승인된 런북을 실행합니다. 그 진단 결과가 다시 intent.md 로 쓰여서 파이프라인 맨 앞으로 들어갑니다. 그래서 여섯 단계가 일직선이 아니고, intent.md 에서 시작해 intent.md 로 돌아옵니다.

1σ, 2σ, 3σ 로 갈수록 모델이 할 수 있는 일을 한 칸씩 늘려 둔 건 처음에 거꾸로 아닌가 싶었습니다. 이상한 정도가 클수록 모델한테 더 많은 걸 맡기는 셈이니까요. 큰 일일수록 사람이 봐야 할 것 같았거든요. 그런데 생각해 보면 큰 일일수록 빨리 손을 써야 하고, 미리 승인된 런북이라는 조건이 붙어 있으니 모델이 새로 판단하는 건 아닙니다. 사람이 미리 해 둔 판단을 모델이 대신 실행하는 겁니다. 그렇게 보면 판단은 여전히 사람이 한 건데, 그 판단을 언제 했는지가 사고 전으로 당겨진 것뿐입니다.

모델을 이렇게 많이 쓰라고 하는 문서가 탐지에서만큼은 모델을 빼라고 못 박은 게 재미있었습니다. 무언가를 잡아내야 하는 일에는 매번 같은 답이 나오는 방법을 쓰고, 잡힌 다음에 그게 무슨 일인지 읽는 데만 모델을 쓰라는 뜻으로 읽었습니다. 제가 훅에서 겪은 문제는 오히려 이 반대쪽에 있었던 것 같습니다. 정해진 규칙으로 잡아내는 것까지는 했는데, 그 규칙이 맞는지는 아무도 안 봤습니다. 탐지를 결정적으로 만드는 것과 탐지 규칙이 옳은 것은 다른 이야기인데, 문서는 앞쪽만 말하고 있습니다.

다섯 개의 파일이 감사 기록이 됩니다

여섯 단계를 묶는 건 단계마다 남기는 파일입니다. 단계마다 다음 단계가 읽을 수 있는 걸 커밋합니다.

Together, the intent, the spec, the plan, the diff and the review findings are the audit trail.

의도, 스펙, 계획, 코드 변경, 리뷰에서 나온 지적. 이 다섯 개가 합쳐져서 감사 기록이 된다는 겁니다. 원칙도 한 줄 있습니다. "Humans remain accountable for every decision that requires judgment." 판단이 필요한 결정은 전부 사람이 계속 책임진다는 거고, 거기에 에이전트 SDLC 에서는 사람의 주의가 검토해야 할 산출물을 따라간다는 설명이 붙어 있습니다.

여기서 좀 멈췄습니다. 주의가 다른 데로 간다고 하면 할 일이 가벼워진 것처럼 들리는데, 실제로는 읽을 게 늘었습니다. 예전엔 코드 변경만 읽으면 됐는데 이제는 의도와 스펙과 계획과 코드 변경과 리뷰 지적까지 읽습니다. 쓰는 쪽이 사람에서 에이전트로 바뀌었을 뿐이고 문서 개수는 줄지 않았습니다.

감사 기록이라는 말도 좀 생각하게 됩니다. 감사는 보통 일이 끝난 다음에 누가 와서 들여다보는 건데, 이 다섯 개 파일은 다음 단계가 바로 읽는 입력이기도 합니다. 나중에 볼 기록과 지금 쓰는 입력이 같은 파일이면 적어도 안 쓰고 넘어가기는 어렵겠다는 생각이 듭니다. 아무도 안 읽는 회의록하고는 처지가 다릅니다.

문서는 줄 단위 리뷰가 원래 오래 버틸 수 없다고 봅니다. 사람이 쓴 코드는 한 줄씩 손으로 읽는 게 말이 됐지만 에이전트가 코드 변경 대부분을 쓰면 따라갈 수 없다는 겁니다. 그 말은 맞다고 생각합니다. 그런데 그렇게 되면 사람은 더 위쪽 문서를 더 꼼꼼히 읽어야 하고, 그건 일이 가벼워진 게 아니라 종류가 바뀐 겁니다. 문서는 이걸 "orchestrating parallel work streams and triaging findings" 라고 적었습니다. 병렬 작업을 지휘하고 탐지 결과를 선별하는 일이죠. 저는 그 선별이 결국 본업이 될 것 같습니다. 코드를 한 줄씩 볼 때는 틀린 게 눈에 걸리는데, 스펙 한 장을 볼 때는 빠진 게 잘 안 보입니다. 빠진 걸 찾는 일이 틀린 걸 찾는 일보다 훨씬 피곤합니다.

plan mode 와 훅은 같은 종류의 게이트가 아닙니다

제일 오래 붙잡고 있던 부분입니다. 문서는 plan mode 와 훅을 둘 다 승인 게이트로 소개하는데, 저는 둘이 전혀 다른 거라고 봅니다.

plan mode 는 엔지니어가 계획을 받아들이기 전까지 클로드가 파일을 고칠 수 없으니 스스로 강제가 된다고 적혀 있습니다. 이건 맞습니다. 파일을 고칠 권한이 있냐 없냐는 모델이 뭐라고 말하든 안 바뀌는 사실이라, 모델이 협조하든 안 하든 상관이 없습니다.

훅은 다릅니다. 훅이 정해진 대로 실행되는 건 맞는데, 훅이 무엇을 검사할지는 훅을 짠 사람이 정합니다. 저는 바로 여기서 실패했습니다. 사이드 프로젝트에 검토를 자동화한 훅을 걸어 두고 넉 달을 썼는데, 나중에 열어 보니 그중 이 레포를 보고 있는 게 하나도 없었습니다. 경로가 안 맞거나, 조건이 절대 참이 안 되거나, 검사하는 대상이 제가 실제로 쓰는 것과 달랐습니다. 훅이 있다는 것과 훅이 뭔가를 막고 있다는 것 사이가 그렇게 멀 줄 몰랐습니다.

한 번 확인한 기억이 그대로 믿음이 돼 버리는 것도 비슷합니다. 이 블로그를 돌리는 레포에는 커밋 직전에 도는 시크릿 스캔이 있고, 자격증명 파일을 실수로 스테이지했을 때 실제로 막아 준 적이 있습니다. 그 뒤로 몇 달을 의심하지 않았는데, 정규식만 떼어 내서 가짜 시크릿에 던져 보니 하나도 못 잡았습니다. 제가 가진 자격증명을 기준으로 목록을 만들었으니 제가 안 가진 종류는 전부 통과였던 겁니다.

그래서 훅을 승인 게이트로 쓰라는 말이 저한테는 훅이 검사하는 항목을 계속 의심하라는 말로 들립니다. Test 단계 평가셋이 훅이 바뀔 때마다 돈다고 했지만 그건 바뀔 때 이야기입니다. 처음부터 아무것도 안 잡던 훅은 바뀔 일이 없으니 계속 아무것도 안 잡습니다. 넉 달 동안 조용했던 제 훅들이 딱 그랬습니다. 조용한 게 잘 막고 있어서인지 아무것도 안 보고 있어서인지, 밖에서 보면 구분이 안 됩니다.

AI 한테 PR 리뷰를 맡기는 것도 같은 이유로 조심스럽게 봅니다. 문서는 이 부분을 잘 처리했습니다. 에이전트 리뷰는 여러 단계로 두되 승인 권한은 주지 않고, branch protection 을 거쳐 사람한테서 받게 했으니까요. 리뷰와 승인이 나뉘어 있어야 하고, 그게 흐려지면 검문소와 통행증 발급처가 같아집니다. 저도 예전에 발행 스크립트가 검수 문서에 적힌 합격 표시를 찾아서 통과 여부를 정하게 해 뒀다가 걷어냈습니다. 그 표시를 검사받는 쪽이 직접 쓰고 있었거든요.

계획에서 벗어났을 때 고치는 것도 계획입니다

plan.md 에 대해선 전에 반대하는 글을 쓴 적이 있습니다. 계획을 먼저 세우고 그대로 구현시키라는 절차가 커뮤니티에서 많이 읽히던 때였고, 저는 계획서대로 짰으면 그 버그는 그대로 나갔다고 썼습니다. 그날 고친 버그들은 뒤쪽에 가서야 패턴에 이름이 붙었고, 앞에서 승인받은 설계는 그때 이미 틀린 문서였습니다.

그래서 Build 단계는 좀 경계하면서 읽었는데, 그 한 줄에서 생각이 바뀌었습니다.

When implementation departs from the plan, update plan.md in the same commit

구현이 계획에서 벗어나면 같은 커밋에서 계획을 고치라는 겁니다. 제가 반대한 건 "계획대로 구현하라" 였고, 이 문장은 계획에서 벗어나는 걸 정상적인 일로 받아들인 다음에 기록을 맞추라고 합니다. 계획이 지시서가 아니라 지금까지 이해한 걸 적어 둔 메모가 되는 겁니다.

plan.md 가 쓸모 있는 이유도 거기 있다고 봅니다. 계획이 코드를 정하는 게 아니라, 어떻게 바꿀지가 한 사람 머릿속에만 있는 상태를 끝내는 데 쓸모가 있습니다. 문서가 예전 방식을 "stays in the engineer's head" 라고 했는데, 에이전트가 코드를 쓰는 환경에서는 그 머릿속이 사람 것도 아닙니다. 세션이 닫히면 같이 없어집니다. 그러니 계획이 틀어졌어도 고쳐서 남겨 두는 게 맞습니다. 틀린 계획을 지우지 않고 고쳐 둔 기록이 나중에는 제일 많은 걸 알려 줄 것 같기도 합니다. 처음에 뭘 잘못 알고 있었는지가 거기 남으니까요.

만약 제가 그때 이 한 줄을 알고 있었다면 계획서를 쓰는 데 그렇게까지 반대하지는 않았을 것 같습니다. 제가 싫었던 건 계획을 쓰는 일이 아니라, 쓴 계획을 바꾸면 안 되는 것처럼 대하는 태도였습니다. 계획을 바꿔도 된다고 처음부터 적어 두면 계획서는 약속이 아니라 일기 비슷한 게 됩니다. 그건 써 볼 만하다는 생각이 듭니다. 다만 같은 커밋에서 고치라는 조건을 사람이든 에이전트든 매번 지킬지는 또 모르겠습니다. 바쁠 때 제일 먼저 빠지는 게 그런 일이니까요.

판단이 필요한 결정은 누가 정하나

다 읽고 남은 건 이 질문입니다. 판단이 필요한 결정은 사람이 책임진다는 원칙에는 반박할 데가 없는데, 어떤 결정이 판단이 필요한 결정인지는 이 문장이 정해 주지 않습니다.

문서에서는 그 경계가 조직의 분류에 맡겨져 있습니다. 고위험으로 분류된 건 테크 리드한테 가고, 규제 대상 코드는 사람이 읽고, 미리 승인된 런북은 3σ 에서 자동으로 실행됩니다. 그 분류를 누가 어떤 근거로 만드는지는 비어 있습니다. 조직마다 다를 수밖에 없는 부분이라 비워 둔 것 같은데, 사고는 보통 여기서 납니다. 저는 자동으로 돌던 게 아무것도 안 잡고 있었다는 걸 넉 달 뒤에 알았고, 그 넉 달 동안 제 분류로는 그게 "자동화해도 되는 일" 이었습니다. 분류는 한 번 정하면 잘 안 바뀝니다. 처음에 자동화해도 되는 쪽에 넣어 둔 일은 아무 일이 없는 한 계속 그쪽에 있고, 아무 일이 없다는 게 정말 아무 일이 없어서인지 아무도 안 봐서인지는 앞에서 말한 훅이랑 똑같이 구분이 안 됩니다.

도구를 파는 회사가 프로세스까지 같이 내놓았다는 것도 마음에 걸립니다. 여섯 단계가 전부 제품 기능 이름으로 채워져 있고, plan mode 와 스킬과 훅과 서브에이전트와 MCP 가 단계마다 답으로 놓여 있습니다. 저는 이 문서를 "우리 프로세스를 여기에 맞추자" 로 읽으면 안 되고, "우리 프로세스에서 어디가 이 문서가 말하는 병목인지 찾자" 로 읽어야 한다고 봅니다. 앞쪽으로 읽으면 산출물 다섯 종부터 만들어 놓고 쓸 데를 나중에 찾게 되는데, 그건 제가 훅 열두 개를 걸어 놓고 넉 달 뒤에 열어 본 것과 같은 순서입니다.

코스는 아직 다 못 봤습니다. Test 단계 평가셋 차시는 글에 적힌 것보다 구체적인 게 있을까 싶어서 그것부터 볼 생각입니다. 제 CLAUDE.md 와 스킬을 결과가 알려진 과제에 던져 보는 건 당장 해 볼 수도 있는 일이고요.