소망은 법이 아니다 — AI 시대의 스펙 운영기

AI 에이전트가 코드의 대부분을 쓰는 체제로 넘어오면서, 나는 오래 믿어 온 전제 하나가 무너지는 걸 봤다. "좋은 개발자는 가이드를 읽고 지킨다"는 전제다. 에이전트는 성실하게 읽고도 다르게 쓰고, 사람은 이제 그 산출량을 눈으로 다 볼 수 없다. 규칙을 문서에 적어 두는 것과 규칙이 지켜지는 것 사이의 간극 — AI 시대의 개발 조직이 가장 먼저 마주치는 문제가 이것이라고 생각한다. 우리 팀이 그 간극을 어떻게 메워 왔는지, 코딩 가이드와 도메인 헌법과 이슈 트래커가 어떻게 한 루프로 맞물려 도는지를 정리한다.

한 줄 요약: 스펙을 헌법(불변식)·계약(수용 기준)·실행형(테스트·아키텍처 규칙) 3층으로 나누고, 규칙마다 "누가 집행하는가"를 정했다. 사람의 일은 코드를 쓰는 것에서 결정하고, 비준하고, 표본을 감사하는 것으로 옮겨 갔다. 이슈 트래커는 초안실이고 git이 법전이다.

배경

우리 솔루션은 배출·운반·처리 사업자 사이의 주문, 배차, 계약, 정산을 다루는 B2B 물류 플랫폼의 백엔드다. 도메인 규칙이 두껍다 — 원장은 덮어 쓰면 안 되고, 정산은 검수에서만 파생되며, 상대 장부는 규칙을 아는 쪽이 세운다. 이런 불변식이 수십 개 있고, 구현의 대부분은 AI 에이전트가 쓴다. 사람이 병목이 아니라 방향타여야 하는 체제다.

문제를 느낀 계기

• 가이드는 자라는데 준수는 늘지 않았다. 코딩 가이드가 수십 조를 넘기자 아무도 통독하지 않게 됐다. 사람도 그런데, 에이전트는 매 세션 처음 읽는다. "읽고 지켜라"는 집행이 아니라 소망이었다.
• 리뷰가 고무도장이 되어 갔다. 에이전트가 하루에 만드는 diff를 사람이 전수 검토하는 건 산술적으로 불가능하다. 전수 검사를 명목으로 유지하면 실제로는 훑고 승인하게 된다 — 검사가 아니라 의식이 되고, 이 단계의 'LGTM'은 '꼼꼼히 읽었다'보다 '흐름을 막고 싶지 않다'에 가깝다.
• 규칙의 출처가 없었다. 왜 있는지 모르는 규칙은 반박도 개정도 못 한다. 낡은 규칙이 계속 인용되고, 필요한 규칙은 문서 밖 누군가의 머릿속에만 있었다.
• 스펙과 코드가 말없이 갈라졌다. 문서를 고치지 않고 동작을 바꾸는 일이 반복되면 문서는 화석이 된다. 화석이 된 문서는 AI에게 그대로 잘못된 컨텍스트가 된다 — 사람은 낡은 문서를 의심이라도 하지만, 에이전트는 믿는다.

제약

• 스펙 개정이 비싸면 반드시 우회한다. 절차가 무거우면 사람들은 코드만 고친다. 개정은 싸야 한다 — 그래서 개정 초안은 AI가 쓰고, 사람은 비준만 한다.
• 모든 동작을 스펙화할 수 없다. 백과사전식 스펙은 유지 비용으로 무너진다. 무엇을 스펙으로 승격하고 무엇을 코드에 맡길지의 선이 필요하다.
• 사람의 주의력은 이제 가장 희소한 자원이다. 어디에 쓸지를 설계하지 않으면 아무 데도 쓰이지 않는다.

선택지

1. 문서 + 리뷰어 재량 (관행) 장점: 익숙하다. 단점: 위에서 본 그대로 — 산출량이 사람의 눈을 넘는 순간 무너진다.

2. 전부 자동화 장점: 사람이 병목에서 빠진다. 단점: "정산은 검수에서만 파생된다" 같은 의미론적 불변식은 기계가 판정할 수 없다. 자동화할 수 없는 규칙이 반드시 남는다.

3. 규칙마다 집행처를 정하고, 스펙에 권위와 생명주기를 부여 장점: 기계가 잡을 수 있는 것은 기계가, 못 잡는 것만 사람과 AI 리뷰가 진다. 단점: 체계 자체의 운영 비용.

3이다. 핵심 문장은 이것이다 — 스펙과 코드가 다르면 스펙이 이긴다. 말없이 갈라지는 것만 금지다.

결정

스펙은 3층이다. 헌법(도메인 불변식 — 지속, 개정으로만 변경), 계약(작업 단위의 수용 기준 — 이슈 본문에 살다가 머지 때 테스트로 남는다), 실행형 스펙(시나리오 테스트·아키텍처 규칙 — red가 곧 불일치 신호). 스펙은 백과사전이 아니다 — 불변식과 수용 기준만 승격하고, 나머지는 코드와 테스트가 스스로를 문서화한다. 스펙이 침묵하는 영역은 코드가 사실상의 스펙이다.

코딩 가이드는 색인이고, 규칙마다 집행 등급이 있다. "통독하지 말고 지금 만지는 파일의 문서만 열어라"가 첫 줄이다. 그리고 모든 규칙에 집행 주체를 박았다 — 저장 즉시 되돌리는 훅, 빌드를 깨는 아키텍처 테스트, 문맥 판단이 필요한 것만 리뷰, 아직 집행 장치가 없는 것은 "냄새"로 분류하고 지켜질 것으로 기대하지 않는다고 명시한다. 기대하지 않는다는 선언이 중요하다 — 집행 없는 규칙을 지켜지는 규칙처럼 취급하는 것이 문서 불신의 시작이기 때문이다. 기존 위반이 많은 규칙은 동결(freeze)로 묶어 신규 위반만 차단하고, 동결 목록은 줄어드는 방향만 허용한다.

헌법 조문에는 생명주기가 있다. 조문 하나는 규칙 한 줄이 아니라 근거·집행처·신분을 가진 레코드다.

### §n {한 줄 제목}
- 신분: 활성 | 전환중(이슈 링크) | 제안됨
- 근거: {설계 결정·사고·이슈 — 근거 없는 조문은 금지. 소망은 법이 아니다}
- 집행: 시나리오테스트(클래스) | 아키텍처테스트(규칙명) | AI리뷰(산문)
- 규칙: {"~해야 한다"보다 "X 시 Y 금지, 대신 Z"}
- 위반 예 / 올바른 예

운영 규칙이 체계의 실질이다. 조문은 도메인당 20조 상한 — 상한이 없으면 헌법도 백과사전이 된다. 폐지해도 번호는 결번으로 남긴다 — 인용의 안정성이 규칙의 유통을 만든다. 신분은 구현 여부가 아니라 비준 여부를 추적한다 — 제안됨 조문으로는 리뷰어가 차단하지 못하므로, 방금 세운 규칙의 회귀를 막으려면 비준까지 끝내야 한다. 그리고 개정은 동작을 바꾸는 코드와 같은 PR로 나간다 — 권위는 스펙이 먼저지만, 배송은 함께다.

조문이 태어나는 길은 둘이다. 새 설계 결정이 선언으로 먼저 서고 집행 테스트가 그린임을 대조해 활성화되는 길, 그리고 역추출 — 이미 코드와 테스트가 지키고 있는 불문율을 캐내 성문화하는 길. 후자가 생각보다 크다. 헌법의 절반 가까이는 새로 정한 규칙이 아니라, 이미 지켜지고 있었지만 아무도 문장으로 갖고 있지 않던 규칙이었다.

AI 리뷰에는 인용 의무와 기각 로그가 있다. 리뷰 지적은 근거 조문을 인용해야 하고, 인용 못 하는 지적은 "제안"으로 강등된다 — AI의 그럴듯한 지적이 무근거 권위가 되는 것을 막는 장치다. 사람이 기각한 지적은 조문별로 누적 기록하고, 반복 기각되는 조문은 재판에 회부한다(개정·문구수정·재확인 중 판결). 리뷰어가 조문과 코드베이스의 광범위한 모순을 발견하면 위반 지적과 별도로 "규칙 의심"을 보고할 의무가 있다 — 규칙을 의심하는 채널이 없는 규율은 반드시 부패한다.

이슈 트래커 Plane은 초안실이고, git이 법전이다. 결정의 맥락, 대안 비교, 수용 기준은 이슈에서 산다. 커밋은 이슈 번호를 인용하고, 머지되는 순간 지속 가치는 전부 리포로 승격된다 — 수용 기준은 테스트 코드로, 발견된 불변식은 헌법 조문으로. 이슈 트래커가 죽어도 법은 남는 구조다. 작업 루프는 이렇게 돈다.

결정(사람 확정, AI 초안) → 수용 기준 → 테스트 번역(AI 작성 → 사람 승인, red 확인)
  → 구현(AI 자율, red→green — 테스트 수정 금지: 테스트 변경은 곧 스펙 개정)
  → 감사(기계 층 + AI 조문 대조 + 사람 표본) → 환류(조문 개정·신설, 사람 비준)

사람의 개입 지점을 보면 이 체계의 의도가 드러난다 — 계약 확정, 테스트 번역 승인, 비준, 그리고 무작위 표본 심층 감사. 전수 검사는 금지다. N개 중 1개를 끝까지 파는 쪽이, 전부를 훑는 것보다 고무도장을 막는다. 운영에서 결함이 탈출했을 때의 부검 질문도 정해져 있다 — "누가 잘못 짰나"가 아니라 "어느 게이트가 놓쳤고 어떻게 보강하나." AI가 쓴 코드의 결함에 사람을 탓하는 건 무의미하고, 게이트를 탓해야 체계가 자란다.

결과와 한계

• 얻은 것: 다섯 도메인 수십 조의 헌법이 실제로 유통된다 — 리뷰 지적이 조문을 인용하고, 설계 결정이 조문 개정으로 남고, 개정이 코드와 같은 PR로 나간다. 사고 회고가 "조문 신설"이라는 정해진 출구를 갖는다.
• 잃은 것: 체계 자체의 운영 비용 — 비준이라는 사람 병목, 동결 목록 관리, 조문 20조 상한을 지키기 위한 통폐합 논쟁.
• 정직한 고백: 감시자를 누가 감시하는가는 아직 절반만 답했다. AI 리뷰어의 적중률을 과거의 실제 버그로 채점하는 것, 테스트의 질을 뮤테이션 테스팅으로 재는 것은 설계만 있고 도입 전이다.

앞으로 — 사람의 일이 무엇이 되는가

가려는 방향은 셋이다. 기계 층의 확장 — 산문 규칙 중 구문 신호가 생긴 것을 계속 아래층인 정적 분석과 아키텍처 테스트로 내려보낸다. 산문에 남는 규칙이 적을수록 의미론 리뷰의 밀도가 올라간다. 감시자 채점 — 과거 버그 diff를 함정으로 재생해 AI 리뷰어를 측정하고, 분기마다 조문별 위반 수를 세어 죽은 조문을 적발하는 사문화 감사를 정례화한다. 계약층의 정식화 — 지금은 헌법이 먼저였고, 작업 단위의 수용 기준을 템플릿으로 강제하는 것은 다음 단계다.

AI 시대의 개발을 한 문장으로 요약하라면 이렇게 쓰겠다. 코드를 쓰는 능력의 값은 내려가고, 무엇이 옳은지를 문장으로 확정하는 능력의 값은 올라간다. 가이드·헌법·트래커로 이루어진 이 체계는 결국 그 확정 문장들이 낡지 않게 관리하는 장치다 — 법전이 살아 있는 한, 쓰는 손이 사람이든 기계든 결과는 규율 안에 있다.