AI에게 코드를 시키기 전에 먼저 써야 할 문서, Anthropic이 꼽은 intent.md

요구사항 하나가 개발자에게 닿기까지의 길을 떠올려 보면 불편이 보입니다. 아이디어는 백로그 항목이 되고, 사용자 스토리가 되고, 스토리 포인트가 붙고, 정제 회의를 지나며, 그 단계마다 맡은 사람이 바뀝니다. 엔지니어링에 도착한 문장은 처음 제안한 사람의 말에서 몇 걸음 떨어져 있습니다. 이 여정이 느려도 견딜 만했던 것은 코드를 짜는 구간이 훨씬 더 느렸기 때문입니다. AI가 코드를 몇 분 만에 쓰는 지금은 그 앞쪽이 눈에 띄게 길어졌습니다. Anthropic은 2026년 8월 21일 공개한 ’AI-native SDLC 플레이북’에서 이 구간을 파일 한 장으로 줄이는 쪽을 택했고, 그 파일이 intent.md입니다. 이 글은 “코드보다 먼저 무엇을 써야 하는가”라는 질문 하나를 붙들고, 그 한 장이 어떻게 쓰이고, 누구의 손을 거치고, 어디에 놓이고, 나중에 어디서 되돌아오는지를 플레이북 본문과 Claude Academy 강의(14강, 약 1시간) 기준으로 따라갑니다.

요구사항이 엔지니어에게 닿을 때쯤엔 다른 말이 되어 있다

소프트웨어 개발 수명주기(SDLC)는 기획, 설계, 구현, 테스트, 배포, 운영으로 이어지는 일의 흐름입니다. 강의 소개는 진단을 한 줄로 요약합니다. AI는 코드를 훨씬 빠르게 쓰게 됐지만 코드 주변의 과정은 그 속도를 따라오지 못했다는 것입니다. 무엇을 만들지 정하는 일과 만들어진 것을 검토해 내보내는 일이 여전히 사람의 속도로 돌아가므로, 코드가 빨라질수록 앞뒤의 느림이 더 크게 보입니다.

플레이북의 처방은 각 단계가 끝날 때 파일 하나를 커밋하고, 다음 단계가 그 파일을 읽게 하는 것입니다. 사람은 모든 단계를 손으로 하는 대신 파일과 파일 사이의 관문에서 검토하고 결정합니다. 커밋 기록에 작성자와 시각, 수정 이력이 남으므로 감사 자료가 따로 필요하지 않습니다. 이 구조에서 첫 번째 파일이 intent.md입니다. 플레이북은 이것을 사람이 읽을 수 있으면서 기계가 곧바로 집어 쓸 수 있는 ’원시 명세(proto-spec)’로 설명합니다.

강의 소개는 이 접근을 열두 개의 ’플레이’로 나누어 다섯 줄짜리 의존 그래프로 그립니다. 맨 윗줄의 여섯 개는 선행 조건이 없는데, 계획 단계의 intent 작성, 구현 단계의 계획 모드·CLAUDE.md·스킬, 테스트 단계의 피드백 루프, 배포 단계의 훅(승인 관문)입니다. 어느 조직이든 이 가운데 하나를 골라 오늘 시작할 수 있다는 뜻이고, intent 작성은 그 첫 번째입니다. 반대로 설계 단계의 요구사항·설계 플레이는 intent 작성과 스킬이 먼저 있어야 하고, 운영 지표로 고리를 닫는 플레이는 CI/CD와 intent 작성이 있어야 합니다. 어디서 시작하든 intent.md가 여러 플레이의 뿌리에 놓입니다.

첫 답은 제안자가 자기 말로 남기는 한 장

그렇다면 이 한 장은 누가 어떻게 쓰나요? 강의의 답은 “제안자가 Claude와 이야기하면서”입니다. 출발점은 세 가지로 열려 있습니다. 사람이 아이디어를 직접 꺼낼 수도 있고, 접수된 티켓이 시작일 수도 있고, 운영 중 울린 경보가 시작일 수도 있습니다. 어느 쪽이든 제품 책임자가 검토하고 고친 뒤에 커밋하는 것은 같습니다. 사람이 직접 쓰는 경우의 순서는 다섯 걸음입니다.

1. 만들려는 일을 Claude에게 자기 말로 설명한다. 지금 못 하는 것, 영향받는 사람, 나아진 모습, 이번에 하지 않을 것을 담는다. 격식은 필요 없다.
2. Claude가 범위, 사용자, 제약, 성공 기준을 분석가처럼 되묻는다. 아이디어가 구체적으로 잡힐 때까지 주고받는다.
3. Claude가 조직의 템플릿에 맞춰 intent.md를 쓴다.
4. 작성자가 Claude가 잘못 이해한 부분을 고친다.
5. 공유 저장 위치에 커밋한다. 작성자와 시각이 남고 제품 책임자가 이어받는다.

강의에는 문장 단위의 프롬프트가 나와 있지 않으므로, 아래는 편집부가 이 글을 위해 꾸민 가상의 대화입니다. 눈여겨볼 것은 불평 한 줄로 시작한 대화가 질문 세 번 만에 제약과 범위를 드러낸다는 점입니다.

시작 문장은 짧아도 됩니다. 아래처럼 코드가 아니라 질문부터 받도록 요청하면 충분합니다.

문의 목록 내보내기 기능을 추가하려고 해. 범위, 사용자, 제약, 성공 기준을
네 가지 질문으로 먼저 물어봐 줘.

팀에 맞는 틀이 굳어지면 스킬로 만들어 두는 편이 좋습니다. Claude Code의 스킬은 .claude/skills/<이름>/SKILL.md에 두는 지침 묶음이고, 프로젝트 안에 커밋하면 팀 전체가 같은 이름의 슬래시 명령으로 부릅니다. 예전의 .claude/commands/ 파일도 같은 방식으로 동작하며 지금은 스킬과 하나로 합쳐져 있습니다. 아래는 편집부가 공식 문서의 형식에 맞춘 예시이고, $ARGUMENTS 자리에 /new-intent 뒤에 적은 한 줄이 들어갑니다.

---
name: new-intent
description: 아이디어를 질문으로 구체화해 intent/ 폴더에 intent.md로 정리한다
disable-model-invocation: true
---

다음 아이디어를 intent.md로 만든다: $ARGUMENTS

1. 코드나 해법을 쓰지 말고, 범위·사용자·제약·성공 기준을 먼저 물어본다.
2. 답이 모이면 문제 / 기대하는 결과 / 영향받는 사용자와 시스템 / 제약 / 열린 질문 순서로 정리한다.
3. 모르는 것은 지어내지 말고 열린 질문에 적는다.
4. intent/ 폴더에 파일로 저장하고 작성자와 상태(draft)를 머리줄에 적는다.

disable-model-invocation: true를 켜면 Claude가 스스로 이 스킬을 불러 쓰지 않고 사람이 /new-intent를 입력했을 때만 실행됩니다. 새 문서를 시작할지는 사람이 정하는 편이 낫기 때문입니다. 3번 줄의 “지어내지 말고 열린 질문에 적는다”도 같은 이유로 넣었습니다. 빈칸을 그럴듯한 문장으로 메우는 일을 막고, 답이 없는 항목을 설계 단계가 이어받게 합니다.

두 번의 사람 손도 놓치면 안 됩니다. 작성자가 Claude의 오해를 고치고, 제품 책임자가 검토해 수락하거나 닫습니다. Claude가 쓴 파일을 그대로 올리면 문서는 쓴 사람이 사라진 채 권위만 갖게 됩니다.

다섯 항목짜리 틀에 청구 상태 건을 채우면

플레이북이 보여 주는 템플릿은 제목 줄, 작성자와 상태 줄, 그리고 다섯 항목입니다. 플레이북은 이것을 조직이 자기 틀로 바꿔도 되는 예시로 제시합니다.

# Intent: 클레임 상태 셀프서비스

작성자: 고객지원 담당 · 상태: draft

## 문제
## 기대하는 결과
## 영향받는 사용자와 시스템
## 제약
## 열린 질문

강의가 드는 예시는 보험 청구 처리 상태 조회입니다. 아래 표의 가운데 칸이 공식 예시의 내용이고, 오른쪽 칸은 그 항목이 뒤 단계에서 무엇을 가능하게 하는지를 편집부가 읽은 것입니다.

항목	공식 예시의 내용	편집부 해석
문제	고객이 청구 진행 상황을 묻느라 콜센터에 전화하고, 청구 담당자가 통화 시간의 약 3분의 1을 상태 문의에 쓴다	해법이 아니라 불편과 겪는 사람을 적는다
기대하는 결과	고객 포털이 청구 상태, 다음 단계, 예상 일자를 보여 준다	끝났다고 판단할 기준이 여기에 들어간다
영향받는 사용자와 시스템	청구 담당자, 포털 팀, 청구 핵심 API	구현자가 어디까지 손대도 되는지의 경계
제약	포털 세션에 개인정보를 새로 넣지 않는다. 기존 인증만 쓴다	코드 한 줄 없이도 넘지 말 선을 긋는다
열린 질문	제3자 손해사정인에게도 접근을 열어야 하는가	지우지 않고 설계 단계로 넘겨 답을 받는다

여기서 숫자를 읽는 법을 짚어 둡니다. ’약 3분의 1’은 이 예시 안에서 청구 담당자의 통화 시간 중 상태 문의가 차지하는 몫으로 설정된 값입니다. 업계 평균이나 실측 통계가 아니라 문서를 쓰는 법을 보여 주려는 설정이니 내 조직의 값으로 바꿔 읽어야 합니다. 강의가 지표로 내세운 ’여러 주에서 몇 시간으로’도 줄어들기를 기대하는 방향입니다. 측정한 결과가 아닙니다.

이 칸들이 얼마나 쓸모 있었는지는 두 가지 숫자로 따집니다. 선행 지표는 첫 대화부터 커밋된 intent.md까지 걸린 시간으로, 깃 기록에서 그대로 읽습니다. 후행 지표는 둘입니다. 하나는 제품 책임자가 닫지 않고 설계 단계로 수락한 비율(생존율)이고, 다른 하나는 같은 변경의 첫 spec.md가 커밋된 뒤에 intent.md를 고친 횟수입니다. 수정 횟수가 많다면 처음 문서에 빠진 것이 많았다는 신호입니다.

파일을 어디에 두고 누가 읽는가

문서를 쓰는 사람과 읽는 사람이 다르므로 둘을 이어 줄 공유 장소가 필요합니다. 강의는 이 장소를 ’intent 홈’이라 부르고 경우를 나눕니다. 제품이 하나면 그 제품 저장소 안의 intent/ 폴더입니다. 코드와 같은 곳에 있어야 문서와 코드가 함께 움직입니다. 여러 저장소에 걸친 일이면 전용 intent 저장소를 쓰는데, 이 경우에만 정당화된다고 강의는 못박습니다. 모노레포라면 저장소 안의 디렉터리 하나입니다. Jira처럼 이미 쓰는 요구사항 도구가 있다면 저장소를 원본으로 삼을지, 기존 도구를 원본으로 삼을지, 둘을 링크로만 이을지를 정하고, 산출물마다 원본이 되는 시스템을 하나로 정해야 한다는 것이 요점입니다.

그림 1. 저장소 안 배치 예시. 파일 이름과 계층은 편집부가 잡았고 공식 규격이 아니다

그림에서 먼저 볼 곳은 intent/ 아래입니다. 변경 하나가 폴더 하나를 받고 그 안에 세 문서가 차례로 쌓입니다. 강의가 설명하는 것은 여기까지이고, CLAUDE.md에는 “작업 문서는 intent/ 아래” 정도의 위치만 한 줄 적습니다. 스킬은 .claude/skills/ 밑에 따로 둡니다. 이 폴더에 쓸 수 있는 사람이 곧 조직의 문서를 바꿀 수 있는 사람이므로 쓰기 권한은 한 번 정해 두어야 합니다.

읽는 쪽의 역할도 정해져 있습니다.

• 제품 책임자intent 홈을 지켜보며 검토하고 수락한다. 설계 단계로 넘길지 정하고, 결정은 병합 또는 닫기 검토로 기록된다
• 작성자(제안자)Claude가 잘못 이해한 부분을 커밋 전에 고친다
• 기술 담당자intent 홈을 만들고 쓰기 권한을 정하며, 템플릿을 스킬로 만들어 리드의 승인을 받는다
• Claude질문하고 정리한다. 티켓이나 경보에서 에이전트가 쓴 intent도 같은 관문을 지난다

기술 팀이 해 두는 일은 일회성 설정입니다. 비개발자에게 필요한 것은 claude.ai나 Cowork 같은 Claude 접근과 합의된 템플릿뿐이고, 깃을 모르면 GitHub 같은 버전 관리 커넥터를 연결해 Claude가 대신 커밋하게 하면 됩니다. 강의가 이 점을 중요하게 보는 이유는 기획자나 운영 담당자가 깃을 몰라도 같은 저장소에 문서를 남길 수 있어야 제안자와 개발팀 사이의 중간 단계가 사라지기 때문입니다.

수락되면 spec.md가, 승인되면 plan.md가 된다

intent.md가 수락되면 두 번째 문서가 이어집니다. 아래 그림은 문서 네 장이 어떤 관문을 지나 코드와 운영으로 가는지, 그리고 운영에서 첫 칸으로 돌아오는 길이 어디인지를 한 장에 그린 것입니다. 초록 영역의 세 문서에서 각 칸 아래의 ’게이트’가 그 문서를 다음으로 넘기는 사람입니다.

그림 2. 문서 네 장과 관문 네 곳. 점선은 운영 신호가 새 intent.md로 돌아오는 길

초록 영역 안에서는 한 줄로 흐르고, 코드와 운영 영역에서 아래로 꺾여 주황색 선으로 되돌아옵니다. 이 되돌아옴은 뒤에서 따로 풉니다. 먼저 두 번째와 세 번째 칸을 봅니다.

설계 단계에서 제품 책임자는 조직의 브랜드·보안·컴플라이언스·UX 정책을 스킬로 불러 놓은 세션에 intent.md를 붙이고, Claude에게 사양서를 쓰게 하면서 우려 사항을 표시하게 합니다. 처음에는 손으로 돌리고, 익숙해지면 조직 단위 슬래시 명령으로 굳힙니다. 더 나아가면 수락된 intent가 병합될 때 비대화형 작업이 돌아 spec.md를 풀 리퀘스트로 올리게 할 수도 있습니다. 이때 제품 책임자의 일은 그 PR을 검토하는 것으로 줄어듭니다. 사양서에 들어가는 것은 원본 intent와 적용한 스킬을 적은 머리줄, 번호 붙은 요구사항(예시에서는 R1~R4), 설계, intent의 제약이 어떻게 충족되는지 보이는 대응표, 이월된 열린 질문, 그리고 담당자가 지정된 우려 사항입니다.

규칙끼리 부딪히는 곳이 여기서 먼저 드러납니다. 강의의 예시에서 포털 UX 스킬은 모든 상태에 날짜를 표시하라고 하고, 브랜드 보이스 스킬은 지급일을 약속처럼 쓰지 말라고 합니다. 둘을 문자 그대로 지킬 수 없으므로 Claude가 충돌을 우려 사항으로 올리고 ’예상 일자’라는 라벨을 제안하며 결정은 컴플라이언스 담당에게 넘깁니다. 이런 충돌이 코드 리뷰가 아니라 문서 단계에서 잡힌다는 점이 설계 플레이의 값입니다. 우려 사항은 엔지니어링이 사양서를 보기 전에 각 정책 담당자와 먼저 풀고, 진행 여부는 사람이 정합니다.

사양서가 수락되면 Claude Code의 계획 모드가 시작됩니다. 엔지니어는 intent.md와 spec.md를 주고 바뀔 파일, 작업 순서, 증명할 테스트를 적은 계획을 요청합니다. 무엇이 깨질 수 있는지, 가장 위험한 단계가 무엇인지, Claude가 버린 대안이 무엇인지를 물어 가며 “대화를 못 본 엔지니어가 계획만 보고 구현할 수 있는” 수준까지 다듬습니다. 계획 모드에서 Claude는 코드베이스를 읽을 수만 있어서, 엔지니어가 계획을 수락하기 전에는 파일을 고치지 못합니다. 수락한 계획이 plan.md로 커밋됩니다.

예시의 plan.md는 이렇습니다. 새 StatusPanel.tsx를 만들고 청구 API의 status.py와 test_status.py를 고칩니다. 순서는 기존 인증 뒤에 상태 엔드포인트를 만들고, 60초 캐시를 둔 패널을 짓고, 포털 내비게이션에 연결하는 것입니다. 위험으로는 청구 핵심 API가 초당 50요청으로 제한되어 있어 패널이 반드시 캐시해야 한다는 점을 적습니다. 증명은 청구 상태 네 가지를 시험하고 필드가 하나라도 더 나오면 실패하는 테스트, 승인된 시안과 화면을 대조하는 스크린샷입니다. 앞에서 intent의 열린 질문이 사양서로 이월되고, 사양서의 제약이 계획에서 위험과 증명으로 바뀌는 것을 따라가는 구조입니다. 구현이 계획에서 벗어나면 같은 커밋에서 plan.md를 고치게 하고, 훅으로 이를 강제할 수도 있습니다.

네 번째 관문은 코드 쪽에 있습니다. 검토된 PR이 병합되려면 코드 소유자의 승인이 필요합니다. 강의는 이 승인을 분기 보호 규칙이 요구하는 것으로 설명하고, 저장소 루트의 REVIEW.md에 버그·보안·컴플라이언스 세 패스의 기준을 기술 리드가 적어 두는 방식을 소개합니다.

CLAUDE.md에 넣을 것과 intent로 뺄 것

여기서 자연스러운 의문이 하나 생깁니다. 저장소에 이미 CLAUDE.md가 있는데 왜 문서를 하나 더 두나요? 둘은 같은 마크다운이고 모두 Claude가 읽지만 답하는 질문이 다릅니다.

	CLAUDE.md	intent.md
답하는 질문	이 저장소에서 어떻게 일하나	이번에 무엇을, 왜 만드나
담는 것	빌드·테스트 명령, 코드 규칙, 구조 메모	문제, 기대 결과, 제약, 열린 질문
위치	./CLAUDE.md 또는 ./.claude/CLAUDE.md	intent/ 폴더
읽히는 때	세션이 시작될 때마다	해당 작업을 할 때
늘어나는 방식	가끔 다듬음	작업마다 한 장씩 쌓임

크기가 가르는 기준이 됩니다. Claude Code 공식 문서는 CLAUDE.md를 파일당 200줄 아래로 유지하라고 권합니다. 길수록 컨텍스트를 더 쓰고 지시를 따르는 정도가 떨어지기 때문입니다. @경로 임포트는 정리에는 도움이 되지만 가져온 파일도 함께 로드되므로 비용은 줄지 않습니다. 이번 작업의 배경과 요구사항을 거기 넣기 시작하면 금방 한도를 넘으니, 작업 단위의 내용은 intent.md로 빼고 CLAUDE.md에는 위치 한두 줄만 둡니다. 특정 폴더에만 해당하는 규칙은 .claude/rules/에 경로를 지정해 두면 그 파일을 다룰 때만 로드됩니다. 처음 만들 때는 /init이 코드베이스에서 빌드 명령과 규칙을 읽어 초안을 써 줍니다.

갱신 시점에 대해 강의는 간단한 규칙을 줍니다. Claude가 같은 실수를 두 번 하면 그 교정을 CLAUDE.md에 넣으라는 것입니다. 작업별 내용은 intent로, 반복되는 규칙은 CLAUDE.md로 나뉩니다. 오래 쓰다 보면 서로 모순되는 줄이 생기는데, /doctor prompt-audit(Claude Code 2.1.283 이상)을 실행하면 CLAUDE.md, AGENTS.md, .claude/ 아래 규칙·스킬·명령까지 훑어 낡았거나 서로 충돌하는 지시를 보고서로 보여 주고, 고칠지는 사용자가 정합니다. 로드되는지 의심되면 /context를 열어 Memory files 목록을 확인합니다.

같은 문서 체계 안에 있는 다른 이름도 구분해 둡니다. 저장소에 AGENTS.md만 있고 CLAUDE.md가 없으면 Claude Code는 AGENTS.md를 직접 읽습니다(2.1.277 이상). 둘 다 있으면 기본값으로 CLAUDE.md만 읽으므로 CLAUDE.md가 AGENTS.md를 임포트해야 합니다. 자동 기억(auto memory)은 사람이 아니라 Claude가 교정 내용을 바탕으로 스스로 쓰는 노트이고, 세션마다 앞부분 200줄 또는 25KB가 로드됩니다. 사람이 쓰는 규칙서, 작업마다 쌓이는 의도, Claude가 적는 메모가 서로 다른 칸입니다.

한 가지는 오해하기 쉽습니다. 이 문서들은 모두 Claude에게 맥락일 뿐 강제 설정이 아닙니다. Claude Code 문서가 직접 밝히듯 어떤 상황에서도 막아야 하는 동작은 PreToolUse 훅으로 따로 막아야 합니다. intent의 제약 항목도 같은 처지입니다. “개인정보를 새로 넣지 않는다”고 적으면 구현자는 그 선을 알고 시작하지만, 어겼는지 걸러 주는 것은 뒤 단계의 리뷰와 훅입니다.

Kiro와 Spec Kit은 같은 자리를 어떻게 채우나

코드 앞에 문서를 두는 방식은 이 플레이북만의 것이 아닙니다. 공식 문서 기준으로 두 가지를 나란히 놓아 봅니다.

	플레이북	Kiro	Spec Kit
흐름	intent → spec → plan → 구현·배포·운영	요구사항(버그는 분석) → 설계 → 작업	constitution → specify → plan → tasks → implement → converge
파일	intent.md, spec.md, plan.md	requirements.md(버그는 bugfix.md), design.md, tasks.md	단계마다 슬래시 명령(/speckit-specify 등)
성격	방법론 문서 + Claude Code 기능 조합	Kiro 제품의 사양(specs) 기능	MIT 라이선스 오픈소스(Python 3.11+, uv로 설치, 저장소 별 약 14.3만)
첫 칸	제안자가 Claude와 대화하며 의도를 남김	요구사항 먼저·설계 먼저 두 방식, 승인 관문 없이 한 번에 만드는 빠른 사양	프로젝트 원칙을 한 번 정하고 사양 단계로

세 곳 모두 코드를 짜기 전에 사람이 읽고 고칠 수 있는 문서를 먼저 확정합니다. 두 도구는 요즘 가지를 뻗고 있습니다. Kiro 문서(2026년 10월 15일 갱신)는 작업 전체를 실행할 때 의존 관계 그래프를 만들어 서로 독립인 작업을 파도 단위로 동시에 돌린다고 설명하고, Spec Kit에는 버그 수정용 확장(/speckit-bug-assess·bug-fix·bug-test)과 아이디어를 평가하는 확장(/speckit-assess-intake부터 assess-decide까지 다섯 단계)이 생겼습니다. 이 평가 확장이 플레이북의 앞단과 가장 가깝지만, 핵심 흐름은 여전히 constitution과 specify로 시작합니다.

플레이북이 다른 점은 두 가지입니다. 사양서보다 앞에 의뢰서 단계를 두고 이것을 개발자가 아니어도 쓸 수 있게 설계했다는 것, 그리고 운영 단계의 신호가 같은 형식의 문서로 첫 칸에 돌아오게 고리를 닫았다는 것입니다. 어느 쪽이 낫다고 가르기보다 문서를 누가 어떤 형식으로 남기느냐의 선택으로 보는 편이 맞습니다.

선을 넘은 지표가 새 intent가 되는 길

고리를 닫는 부분은 플레이북의 유지(Maintain) 단계입니다. 이 단계의 플레이는 셋입니다. 지표를 감시해 이상을 intent로 만드는 고리, 연결된 저장소를 정기적으로 훑는 보안 스캔(호스티드 도구인 Claude Security), Slack에서 사고 채널의 첫 대응자로 일하는 Claude Tag(공개 베타)입니다. 이 가운데 문서 흐름과 가장 직접 닿는 것이 첫 번째이고, 나머지 둘도 한 PR로 끝나지 않는 큰 문제는 intent.md로 써서 첫 칸에서 다시 시작하게 합니다.

지표 고리는 사람도 모델도 아닌 결정적 스크립트에서 출발합니다. 33줄짜리 표준 라이브러리 파이썬 스크립트이고, 모델은 들어 있지 않습니다. 최근 30일의 시간 단위 측정값 720개로 평균과 표준편차를 구해 1σ, 2σ, 3σ 선을 긋고, 가장 최근 값이 어느 선을 넘었는지 판정합니다. 느리게 번지는 이상은 웨스턴 일렉트릭 규칙으로 잡습니다. 최근 5개 중 4개가 1σ 위이거나 연속 8개가 평균 위이면 2σ로 칩니다. 평탄한 지표에서 작은 흔들림이 경보가 되지 않도록 표준편차에 최소값(0.01)을 두고, 기준선에는 최소 24개의 측정값이 있어야 합니다. 이 스크립트는 한 시간마다 돌고, 출력된 등급을 버전 관리되는 bands.yaml에서 찾아 그 등급에 허용된 권한만으로 Claude를 헤드리스로 실행합니다.

등급마다 권한이 다릅니다. 1σ는 기록만 하고 권한이 없습니다. 2σ(느린 이동 포함)는 읽기 전용 진단으로, Read, Grep, gh run view 정도만 허용됩니다. 3σ에서야 변경을 제안할 수 있는데, 길은 풀 리퀘스트를 올려 리뷰 관문에 넣거나 미리 승인된 롤백 런북을 실행하는 둘뿐입니다. 왜 이렇게 층을 나눴는지는 소음의 크기를 보면 드러납니다.

그림 3. 정규분포를 가정한 우연 초과 횟수(편집부 계산). 출처 수치는 하루 약 4회, 한 달 약 16회, 한 달 약 1회

막대 길이의 차이를 보면 됩니다. 정규분포라면 측정값 여섯 개 중 하나가 1σ를, 44개 중 하나가 2σ를, 740개 중 하나가 3σ를 넘습니다. 한 달 720개로는 1σ가 하루 약 네 번, 2σ가 한 달 열여섯 번, 3σ가 한 달 한 번쯤 우연히 선을 넘습니다. 1σ마다 사람이나 에이전트를 부르면 하루 종일 잡음에 시달리므로 기록만 하고, 3σ도 거치는 길을 문이 있는 곳으로 제한합니다. 이 수치는 측정값이 종 모양에 가깝게 분포한다는 가정 위에 있습니다.

릴리스 하나가 12분 만에 되돌려진 기록

강의의 사례를 따라가 봅니다. 청구 상태 엔드포인트의 status_5xx_rate가 감시 대상이고, 앞의 계획서에 적힌 것처럼 포털 패널은 응답을 60초 캐시합니다. 릴리스 4f2c9e1이 StatusPanel.tsx의 CACHE_SECONDS를 60에서 0으로 바꾸자 페이지를 열 때마다 요청이 claims-core까지 가고, 초당 50요청 한도에 걸려 거절이 늘어납니다.

그림 4. 강의 사례의 경과. 간격은 균등하게 그렸고 분 단위는 강의의 시각을 편집부가 계산한 값

릴리스 후 8분에 시간별 점검이 돌아 3σ 등급을 출력합니다. 측정값은 1.9, 평균 0.2, 표준편차 0.02였습니다. 에이전트는 2분 뒤 미리 승인된 rollback-deploy 런북을 실행하고, 12분째에 이전 버전 8c41d07이 다시 서비스됩니다. 8분이라는 탐지 시간은 점검이 정각에 돌았기 때문에 생긴 값이고, 한 시간 주기라면 최악의 경우 이상이 한 시간 가까이 보이지 않을 수 있습니다(편집부 계산). 선행 지표를 ’선을 넘은 때부터 대기열의 intent.md까지’로 잡는 이유가 여기 있습니다.

에이전트는 롤백만 하고 끝내지 않습니다. 계획 단계와 같은 형식으로 intent.md를 씁니다. 문제는 5xx 급증이고, 제약으로는 명세가 상태를 최대 60초 묵은 값으로 허용한다는 것과 claims-core의 한도가 고정이라는 것을 적습니다. 취한 조치로 롤백을 기록하고, 열린 질문으로 실시간 상태를 원한 고객에게 60초가 너무 느린지를 남깁니다. 서비스 소유자나 당직 엔지니어가 이 목록을 보고 즉시 고칠지, 일정에 넣을지, 기각할지를 정하며, 기각된 항목은 정상 범위를 조정하는 데 쓰입니다. 수정이 배포되면 같은 종류의 사고를 잡는 회귀 평가도 하나 늘어납니다. 사례의 평가 status-panel-keeps-its-cache는 4f2c9e1~1에서 시작해 에이전트에게 “더 실시간처럼 느껴지게 해 줘”라고 요청하고, 변경을 claims-api/routes, claims-api/tests, portal/src로 제한하며, make test, make lint, 그리고 CACHE_SECONDS가 1에서 9 사이에 남아 있는지 보는 grep으로 판정합니다.

이 사례에서 plan.md의 위험 칸에 적힌 문장이 운영 단계에서 평가 하나가 되었다는 점이 눈에 띕니다. 계획서가 “캐시가 없으면 한도를 넘는다”고 적어 두었고, 운영이 그 문장을 실제로 시험했고, 시험이 다시 문서와 평가로 돌아왔습니다. 첫 칸이 마지막 칸에 이어진다는 말은 이런 뜻입니다.

고리를 닫는 데 필요한 선행 조건과 한도

이 고리는 앞 플레이가 갖춰져 있어야 돕니다. 플레이북이 이 플레이의 선행 조건으로 꼽는 것은 intent.md 형식, 가속된 PR 리뷰, 행동의 경계가 되는 훅, 그리고 CI/CD의 롤백 경로입니다. 설비로는 지표 저장소(Prometheus나 CI의 API 같은 곳), 저장소 읽기 권한, CI의 비대화형 Claude Code나 웹훅 서비스용 Agent SDK가 필요하고, 트리거는 예약된 GitHub·GitLab 워크플로, 모니터링 웹훅, 네트워크 안의 크론 중에서 고릅니다. 시작은 안정된 기준선이 있는 지표 하나입니다. 강의가 드는 예는 CI 테스트 실패율, 배포 후 5xx 비율, PR 처리 시간이고, 3σ에서 CI 실패율은 불안정한 테스트 격리나 되돌림 PR로, 5xx는 기존 롤백 파이프라인 실행으로, PR 처리 시간의 느린 이동은 경영진용 보고서로 이어집니다.

플레이북은 자기 한도도 밝힙니다. bands.yaml의 기준과 30일 기준선은 예시이고, 유지 단계에는 숫자 목표가 없으며, 플레이마다 선행·후행 지표만 방향으로 제시합니다. 플레이는 모듈식이라 조직이 단계별로 다른 때에 들일 수 있습니다. 자율성을 높이는 자동 모드는 빡빡한 사양과 충분한 테스트가 있는 일상 작업에 맞는 기능으로 설명되고, Claude Security는 기존 정적 분석과 의존성 점검을 대체하지 않고 보강하며 사용량 기준으로 과금되므로 지출 한도를 저장소 크기와 스캔 빈도에 맞추라고 안내합니다. Claude Tag는 공개 베타이고 현재 Slack에서만 쓸 수 있습니다. 문서가 있다고 위험이 사라지는 것이 아니라 검증 장치와 같이 가야 한다는 뜻입니다.

작게 시작하려면 새로 만들 기능 하나에서 질문을 먼저 받아 보면 됩니다. 처음 생각에 없던 제약이 한두 개 드러나는 것이 보통이고, 답이 없는 질문은 열린 질문 칸에 남겨 커밋합니다. 문서가 한 장 쌓이면 같은 기능을 다른 사람이나 다른 에이전트가 이어받을 때 대화 기록 대신 그 파일을 읽습니다. 이어서 첫 대화부터 커밋까지 걸린 시간과 설계 단계로 수락된 비율을 적어 두면, 강의가 말하는 선행·후행 지표를 내 팀의 값으로 볼 수 있습니다.