에이전트가 코드를 쓰는 동안, 결정은 누가 했나
AI 코딩 에이전트를 도입한 팀이 처음 몇 주 동안 느끼는 감각은 대개 비슷하다. 묘사하면 코드가 나타나고, 대부분 동작하고, 속도가 믿기지 않는다. 문제는 그 다음이다. 두 달쯤 지나면 스토리지 레이어가 왜 그렇게 설계됐는지 아무도 설명하지 못하고, 에러 핸들링은 모델이 적당히 추가한 자리에만 존재하며, 보안은 평균적인 퍼블릭 GitHub 레포 수준—즉, 거의 없다—으로 처리돼 있다. 코드가 나쁜 게 아니다. 결정이 없었던 것이다.
이 실패 패턴을 정면으로 다룬 방법론이 AFTER다. dev.to에서 공개된 'AFTER: Your Vibe Code Deserves Better'는 이 문제를 경제 논리로 풀어낸다. AI 생성은 싸고, 인간 판단은 비싸다. 그렇다면 판단을 아껴 써야 할 두 지점은 코드가 생성되기 전과 생성된 후다. Architect First(명세 먼저)와 Test Everything Rigorously(검증 필수)가 그 두 끝을 잡는다. 중간 구현은 에이전트에게 맡긴다.
명세가 곧 통제 평면이다
Spec-Driven Development를 다룬 'SDLC in the AI Era' 역시 같은 진단에서 출발한다. AI는 엔드포인트, 테스트 픽스처, 배포 매니페스트를 초 단위로 만들 수 있다. 하지만 그 속도는 소프트웨어 딜리버리의 비싼 부분—'시스템이 무엇을 해야 하는가'를 결정하고, 구현이 그 의도와 일치하는지 증명하는 일—을 해결하지 못한다. 명세 없이 에이전트를 풀어놓으면 모델은 공백을 자신 있게 채운다. 그렇게 채워진 코드는 컴파일은 되지만 비즈니스 룰을 위반하거나 보안 가정을 무너뜨릴 수 있다.
해결책은 명세를 '임시 입력'이 아니라 딜리버리 전체의 통제 평면(control plane)으로 취급하는 것이다. OpenAPI 계약, 도메인 룰, 데이터 스키마, 아키텍처 결정, 비기능 요건이 버전 관리된 아티팩트로 연결되고, 모든 구현 결정이 그 명세로 역추적 가능해야 한다. 그래야 에이전트가 생성한 코드를 안정적이고 리뷰 가능한 제약 조건과 대조해 평가할 수 있다. 코드는 여전히 중요하지만, 시스템의 유일한 신뢰 가능한 기술(description)이 아니라 명세의 한 투영(projection)이 되어야 한다.
AFTER가 구조화하는 것: 결정 마커와 단계 게이트
AFTER의 실용적 진입점은 단 하나의 파일이다. AFTER.md를 CLAUDE.md나 AGENTS.md로 프로젝트에 넣거나 Cursor 룰에 붙이면, 에이전트는 이 프로토콜을 즉시 따른다. 이유가 흥미롭다. 모델은 이미 TDD, 디자인 문서, RFC, 코드 리뷰 에티켓을 학습했다. AFTER가 가르치는 게 아니라 활성화하는 것이다. DECISION_REQUIRED 마커는 불확실한 에이전트에게 추측 대신 멈추고 인간에게 넘길 수 있는 '명예로운 출구'를 준다. ASSUMPTION 마커는 불확실성이 자신 있는 산문 안에 숨지 않고 명시적 자리를 갖게 한다.
그런데 프로토콜 파일만으로는 세션이 길어지거나 바쁜 날엔 단계가 흐려진다. AFTER의 저자가 이를 해결하기 위해 만든 것이 Go 기반 CLI YVCDB다. 각 단계는 자체 임베디드 프롬프트를 가지며, 모든 단계 이후 인간 승인 게이트가 물리적으로 강제된다. 가장 인상적인 규칙 하나: 디버그 모드에서는 버그를 재현하는 실패 테스트를 먼저 작성하기 전까지 어떤 수정도 허용되지 않는다. 실패 테스트가 곧 버그의 명세다.
공식 문서를 읽지 않은 팀의 천장
세 번째 글 'Agentes de código: já leu a documentação oficial?'은 다른 각도에서 같은 문제를 건드린다. 비공식 설문 결과 대부분의 개발자가 Claude Code나 Cursor를 매일 쓰면서도 공식 문서를 읽은 적이 없다고 답했다. CLAUDE.md가 startup 시 로드되고 모든 요청에 포함되며 인프라 레벨 캐싱으로 재처리 비용을 줄인다는 사실—이건 공식 문서 첫 페이지에 있다. 그걸 모르면 몇 달을 쓰고도 "CLAUDE.md를 막 써보기 시작했다"는 상태가 된다.
이것은 단순한 RTFM 잔소리가 아니다. AI 도구의 공식 문서에는 컨텍스트 윈도우 동작 방식, 압축 메커니즘, 대규모 코드베이스나 모노레포에서의 접근 전략이 명시돼 있다. 2차 출처(블로그, 유튜브, Reddit 스레드)는 그 해석이다. 해석이 틀릴 수 있다는 걸 공식 문서와 대조하지 않으면 알 수 없다. 팀 온보딩 관점에서 이건 명확한 설계 과제다. "이 도구를 공식 문서 기준으로 얼마나 쓰고 있는가"를 팀 역량 평가의 한 축으로 넣어야 한다.
설계 원칙의 선형 흐름: 명세 → 아키텍처 → 품질 검증
세 기사가 수렴하는 지점은 하나다. AI-First 워크플로우에서 에이전트 도입 전에 설계해야 할 것은 프롬프트가 아니라 명세 구조다. 흐름은 단순하다.
- 명세 먼저: 기술 선택, 데이터 스키마, API 시그니처, 제약 조건을 인간이 문서로 결정한다. 이 결정이 없으면 에이전트는 관성으로 선택한다.
- 아키텍처 고정: 명세가 에이전트 컨텍스트에 구조적으로 로드된다. CLAUDE.md, AGENTS.md, Cursor 룰 중 어떤 형태든 상관없다. 중요한 건 기억이 아니라 구조가 강제한다는 점이다.
- 품질 검증: 생성된 코드는 증명되기 전까지 미검증 상태로 취급된다. 테스트는 코드와 동시에 생성되고, 보안 민감 코드는 명시적 마커로 인간 리뷰를 강제한다.
전망: 구조가 에이전트를 길들인다
모델 세대가 올라갈수록 프로토콜 준수는 더 정확해진다. AFTER의 저자 표현을 빌리면, "시스템의 본성에 맞서 싸우는 방법론은 빠르게 낡고, 그것을 타고 가는 방법론은 가치가 오른다." 명세 중심 구조는 모델이 강해질수록 더 잘 작동한다. 반대로 자유 형식 대화에만 의존하는 워크플로우는 에이전트가 정교해질수록 제어하기 어려워진다—더 그럴듯하게 틀리기 때문에.
팀 리드 입장에서 지금 당장 할 수 있는 것은 세 가지다. 첫째, 이번 주 사용 중인 AI 에이전트의 공식 문서를 팀 전체가 읽는 시간을 잡는다. 둘째, 다음 피처 작업 전에 명세 파일 하나를 먼저 쓴다. 아키텍처, 제약 조건, 수용 기준을 포함해서. 셋째, 생성된 코드를 라인 단위로 설명할 수 없으면 머지하지 않는 규칙을 팀 컨벤션으로 명문화한다. 거창한 도구 도입 전에 이 세 가지가 먼저다.