intent.md란? Anthropic AI 네이티브 SDLC의 첫 파일, 작성법과 팀 도입 정리

여러분, AI로 코드는 금방 나오는데 리뷰할 때마다 이 코드를 왜 만들었는지부터 해석하고 있지 않나요? 결론부터 말하면 그 “왜”를 코드보다 먼저 파일로 남기면 됩니다. Anthropic이 이를 위해 제안한 파일이 intent.md입니다. CLAUDE.md 같은 규칙 파일이 아니라, 이 기능을 왜 만드는지, 무엇이 달라져야 하는지, 어떤 제약을 지켜야 하는지를 코드를 짜기 전에 적어 두는 파일이죠.

파일 하나 얘기처럼 보이지만 그 뒤에는 더 큰 그림이 있습니다. Anthropic이 계획부터 운영까지 개발 과정 전체를 AI 기준으로 다시 정리했고, 그 이름이 AI 네이티브 SDLC(AI-native SDLC)입니다. SDLC는 Software Development Lifecycle, 즉 소프트웨어 개발 생명 주기를 말하고, intent.md는 그 흐름의 출발점입니다. 이 글에서는 intent.md를 어떻게 쓰는지부터 보고, 기존 SDLC가 단계마다 어떻게 바뀌는지, 팀에 들이려면 어떤 구조로 시작하면 되는지를 차례로 정리하겠습니다.

intent.md 핵심 요약

• intent.md는 기능 하나를 만들기 전에 무엇을 원하는지, 왜 원하는지, 어떤 제약이 있는지를 적는 마크다운 파일입니다. Anthropic의 AI 네이티브 SDLC 플레이북에서 계획(Plan) 단계의 결과물입니다.
• 템플릿은 Problem, Proposed outcome, Affected users and systems, Constraints, Open questions 다섯 섹션이고, 정해진 형식이 아니라 권장 사항입니다. Problem에는 근거를, Proposed outcome에는 구현 방법이 아니라 달라질 상태를 씁니다.
• Claude Code가 CLAUDE.md처럼 자동으로 불러오는 파일이 아닙니다. 에이전트가 세션마다 읽는 규칙 파일에 읽으라는 지시를 넣어 줘야 합니다.
• AI 네이티브 SDLC는 6단계를 그대로 두되, 단계마다 에이전트가 초안을 만들고 사람이 승인하는 루프로 바꿉니다. 각 단계는 다음 단계가 읽을 결과물을 하나의 레포(또는 한 곳의 저장소)에 커밋합니다.
• intent.md는 “왜”, spec.md는 “무엇을 어떤 설계로”, plan.md는 “어떤 코드를 어떤 순서로 바꾸고 무엇으로 검증할지”에 답합니다.
• 오타나 작은 버그까지 intent를 쓸 필요는 없습니다. 큰 기능 단위부터, 필요한 단계만 하나씩 들이는 게 현실적입니다.

intent.md란 무엇인가

Anthropic이 2026년 8월 21일 공개한 The AI-native SDLC playbook은 개발 과정을 계획(Plan), 설계(Design), 빌드(Build), 테스트(Test), 배포(Deploy), 운영(Maintain) 6단계로 나눕니다. intent.md는 그 첫 단계인 계획의 결과물이고, 플레이북은 이 파일을 이렇게 정의합니다.

The artifact contains what is wanted, why, and under which constraints.

이 파일에는 무엇을 원하는지, 왜 원하는지, 어떤 제약이 있는지가 담긴다.

두는 곳도 간단합니다. 제품이 하나라면 메인 프로젝트 레포 안에 intent/ 폴더를 만들고, 그 안에 intent.md를 커밋해 버전 관리하는 게 가장 단순한 방법입니다. 이렇게 하면 각 결과물이 그 결과물로 만든 코드와 같은 레포에 나란히 남습니다. intent만 모으는 레포를 따로 두는 건 의도가 여러 레포에 걸칠 때나 감수할 만한 비용이고, 모노레포라면 디렉터리 하나면 됩니다.

intent.md 작성법: 다섯 개 섹션과 작성 기준

Anthropic이 제안하는 intent.md 포맷은 다섯 섹션입니다. 섹션마다 답할 질문까지 넣어 바로 복사해서 쓸 수 있는 템플릿으로 옮기면 이렇습니다. Constraints와 Open questions 사이의 Success criteria는 제가 실제 프로젝트에서 하나 더 두는 선택 섹션입니다.

# Intent: [기능 또는 문제 이름]

Author: [이름]
Status: draft

## Problem

- 현재 누가 어떤 문제를 겪는가? 근거는?

## Proposed outcome

- 해결되면 무엇이 달라지는가?

## Affected users and systems

- 사용자:
- 시스템:

## Constraints

- 반드시 지킬 것:
- 범위 밖:

## Success criteria (선택)

- 무엇이 어떻게 바뀌면 성공인가?

## Open questions

- 아직 결정하지 못한 것:

섹션마다 무엇을 넣고 무엇을 뺄지는 플레이북의 공식 예시(고객이 보험 청구 처리 상태를 포털에서 직접 확인하게 하는 기능)를 보면 감이 옵니다.

• Problem: 누가 어떤 문제를 겪는지와 근거를 같이 씁니다. 예시는 “고객이 청구 처리 상태를 물으려고 콜센터에 전화한다”는 문제에 “청구 담당자가 통화 시간의 약 3분의 1을 상태 문의에 쓴다”는 근거를 붙였습니다.
• Proposed outcome: 구현 방법이 아니라 해결된 뒤 달라질 상태를 씁니다. 예시도 “고객이 포털에서 청구 처리 상태, 다음 단계, 예상 일자를 본다”까지만 적습니다. 어떻게 만들지는 spec.md의 몫입니다.
• Affected users and systems: 영향을 받는 사람과 시스템을 모두 적습니다. 예시는 청구 담당자, 포털 팀, claims-core API를 함께 적었습니다.
• Constraints: 반드시 지킬 것과 범위 밖을 같이 씁니다. 예시의 제약은 “포털 세션에 새 개인정보(PII)를 넣지 않는다”, “기존 인증 방식만 쓴다” 두 줄입니다.
• Success criteria(선택): 무엇이 어떻게 바뀌면 성공으로 볼지 적습니다.
• Open questions: 아직 모르는 건 지우지 말고 남깁니다. 다음 단계에서 PO(Product Owner, 제품의 방향을 결정하는 책임자)가 spec을 검토할 때, intent.md의 열린 질문에 답했는지 아니면 다음으로 넘겼는지를 확인하기 때문입니다.

이렇게 채우면 어떤 문제에서 출발해 무엇을 해결해야 하는지가 intent.md 한 파일에 담깁니다.

작성 절차: Claude와 대화로 초안 만들기

intent.md는 의도를 전달하는 파일이라, 개발자가 아니어도 기획자든 PM이든 CS 담당자든 그 의도를 가진 누구나 AI와 대화하며 쓸 수 있으면 됩니다. 시작은 가볍게, 이 정도면 충분합니다.

1. intent.md 템플릿 하나를 정하고 전 구성원과 공유합니다.
2. 그 템플릿을 Claude에게 주고, 의도를 그냥 말로 설명합니다.
3. Claude가 되묻는 질문에 답하면서 의도를 구체화합니다.
4. Claude가 잘못 이해한 부분은 작성자가 고치고, PO가 검토하고 수정해 승인합니다.

예를 들어 “고객이 배송 상태를 자꾸 채팅으로 물어봐서 CS 시간이 낭비되고 있다”고 Claude에게 말하면, Claude가 배송 상태만 보여주면 되는지, 예상 도착일도 필요한지, 고객만의 문제인지 입점 판매자도 영향을 받는지 같은 질문을 하면서 의도를 선명하게 만들어 갑니다. 플레이북도 정해진 형식 언어 없이 자기 말로 설명하면 되고, Claude가 분석가라면 물었을 질문, 즉 범위, 사용자, 제약, 성공했을 때의 모습을 묻는다고 설명합니다.

Claude가 이 대화를 템플릿에 옮기면 초안은 대략 이런 모양입니다. 아직 답하지 못한 질문은 Open questions에 남기고, 대괄호는 팀 상황에 맞게 채울 자리입니다.

# Intent: 배송 상태 문의 줄이기

Author: [CS 담당자 이름]
Status: draft

## Problem

- 고객이 배송 상태를 자꾸 채팅으로 물어봐서 CS 시간이 낭비되고 있다.
- 근거: [최근 배송 상태 문의 건수나 전체 문의 중 비율]

## Proposed outcome

- 고객이 채팅으로 묻지 않고도 배송 상태를 직접 확인한다.
- CS 담당자가 배송 상태 문의에 쓰던 시간이 줄어든다.

## Affected users and systems

- 사용자: 고객, CS 담당자
- 시스템: [배송 상태를 보여줄 화면, 배송 데이터를 가진 시스템]

## Constraints

- 반드시 지킬 것: [팀 정책]
- 범위 밖: [이번에 다루지 않을 것]

## Success criteria

- [배송 상태 문의가 어떻게 바뀌면 성공으로 볼지]

## Open questions

- 배송 상태만 보여주면 되는가, 예상 도착일도 필요한가?
- 고객만의 문제인가, 입점 판매자도 영향을 받는가?

Anthropic은 개발자가 아닌 사람은 claude.ai나 Cowork로 참여하고, git을 모르는 기여자는 GitHub 같은 버전 관리 커넥터로 Claude가 대신 커밋하게 하는 방법도 제시합니다. 조직의 템플릿은 기술 담당자가 스킬로 만들어 두고 리드가 승인하는 방식으로 관리할 수도 있습니다.

intent.md에 대한 오해 두 가지

첫째, intent.md는 Claude Code가 자동으로 읽는 파일이 아닙니다. 2026년 10월 3일 기준으로 Claude Code가 세션을 시작할 때 읽는 건 CLAUDE.md이고, CLAUDE.md 없이 AGENTS.md만 둔 레포라면 AGENTS.md입니다(v2.1.277 이상). intent.md를 자동으로 불러오는 구조는 아직 없으니 이 규칙 파일에 지시를 넣어 줘야 하고, 다른 코딩 에이전트라면 AGENTS.md 같은 규칙 파일에 넣으면 됩니다. 예를 들면 이 정도입니다.

## 기능 작업 규칙

- 기능 작업을 시작하기 전에 intent/<슬러그>/intent.md와 spec.md를 먼저 읽는다.
- intent.md의 Constraints에 범위 밖으로 적힌 항목은 구현하지 않는다.

다만 이건 말로 적은 지시입니다. Claude Code 문서도 AGENTS.md를 읽으라고 말로만 적어 두면 Claude가 그 파일을 열기로 판단할 때만 내용을 본다고 설명하니, 어느 파일을 언제 읽을지 구체적으로 적는 게 좋습니다. 규칙 파일 자체를 어떻게 구조화하는지는 AGENTS.md 구조화 가이드에 따로 정리해 두었습니다.

둘째, 업계 표준이 아닙니다. 다섯 섹션 템플릿도 권장 사항일 뿐이라 팀에 맞게 고쳐 쓰면 되고, intent.md라는 파일 자체도 Anthropic이 제안한 패턴이지 여러 도구가 합의한 표준은 아닙니다.

왜 지금 나왔나: 코드는 더 이상 병목이 아니다

플레이북의 첫 섹션 제목인 “코드는 더 이상 병목이 아니다(Code is no longer the bottleneck)“가 이 질문의 답입니다. 코딩 에이전트 덕분에 코드는 정말 빨리 쓰게 됐지만, 그 앞뒤에 있는 일, 즉 계획을 승인하는 절차, 코드 리뷰, 팀원 간 핸드오프는 그대로입니다. 그러니 전체 개발 속도는 코드 작성이 아니라 그 바깥에서 막힙니다.

저도 2026년 6월에 의도가 중요하다라는 글에서 같은 문제를 다뤘습니다. 코드는 남는데 어떤 의도로 만들었는지는 남지 않아서, 코드 리뷰가 의도를 해석하는 작업이 되어 버린다는 얘기였습니다. 그 글이 “왜 의도가 중요한가”였다면, 이 글은 그 의도를 어떤 파일에, 어떤 절차로 남기느냐에 대한 얘기입니다.

SDLC는 아이디어가 실제 서비스가 되기까지의 전 과정이고, 보통 앞에서 본 여섯 단계로 돕니다. 문제는 단계마다 담당자가 다르고, 기획 문서나 티켓, 특정 담당자의 컨펌으로 다음 단계에 넘어가는 구조라는 점입니다.

기존 SDLC는 코드를 쓰고 구현하는 단계가 가장 오래 걸리고 가장 비싸던 시절에 그 단계를 최대한 효율적으로 돌리려고 만든 것이고, Anthropic은 이제 그 전제가 사라졌다고 봅니다. PRD(Product Requirements Document, 제품 요구사항 문서)를 쓰고, 스프린트 플래닝으로 공수를 잡고, 보안 리뷰를 하는 절차들은 개발이 몇 주, 몇 달씩 이어질 걸 예상했기 때문에 그 사이에 방향을 맞추려고 있던 겁니다.

빌드만 짧아지고 나머지는 그대로

에이전트를 쓰면 몇 주, 몇 달 걸리던 빌드가 몇 시간 단위로 압축됩니다. 그런데 요구사항 검토, 코드 리뷰, 릴리스는 아직 사람이 하고 있어서, 빌드에서 번 시간을 제대로 못 쓰고 있습니다.

리뷰도 마찬가지입니다. 사람이 직접 타이핑한 코드라면 한 줄씩 리뷰하는 게 맞았습니다. 하지만 diff 대부분을 에이전트가 만들면 그 방식으로는 따라갈 수 없습니다. 개발자 세 명이 하루 종일 Claude Code로 PR을 수십 개씩 올리는데 리뷰어는 여전히 그 세 명뿐이라면 어떻게 될까요? 머지 대기열이 계속 쌓이거나, 급하니까 대충 보고 머지하거나, 둘 중 하나입니다.

그래서 Anthropic의 결론은 빌드가 에이전트 덕에 바뀐 만큼 나머지 단계도 그만큼 바뀌어야 한다는 것이고, 그 첫 단계가 intent.md입니다.

AI 네이티브 SDLC란: 직선이 아니라 루프

여섯 단계 자체는 같습니다. 기존 방식은 여섯 단계를 한 방향으로 차례로 거치고, 한 바퀴가 곧 릴리스 한 번입니다. AI 네이티브 SDLC는 단계들이 루프로 이어지고, 루프의 모든 지점에 Claude 같은 코딩 에이전트가 개입합니다. Anthropic은 같은 변화를 agentic SDLC나 AI SDLC라고 부르기도 한다고 덧붙입니다.

결국 차이는 단계마다 무엇이 결과물로 나오느냐입니다. 표로 먼저 보고, 표에 다 담지 못한 내용을 단계별로 덧붙이겠습니다.

단계	기존 방식	AI 네이티브 방식
계획	기획자가 요구사항을 모아 회의와 컨펌을 거쳐 기획서를 손으로 작성	아이디어를 낸 사람이 Claude와 대화해 intent.md 생성
설계	기획서를 디자이너가 Figma로 옮기고 개발자가 다시 구현	intent.md 하나로 한 세션에서 요구사항과 설계 스펙, 필요하면 목업까지
빌드	개발자가 코드를 손으로 작성	코드와 테스트는 에이전트가, 팀 규칙은 규칙 파일과 스킬로
테스트	동작 여부를 알려주는 신호가 늦게 옴	에이전트가 테스트, 빌드, UI 검증을 직접 돌리고 통과할 때까지 수정
배포	사람이 PR을 한 줄씩 리뷰, 품질이 리뷰어 컨디션에 좌우	에이전트 리뷰를 여러 겹, 사람은 결제나 인증 같은 위험한 코드만
운영	새벽 알림 누락, 백로그에 묻히는 티켓	지표 감시 스크립트, 정기 보안 스캔, Slack 첫 대응

계획: 기획서 대신 intent.md

대표, 영업, CS 같은 이해관계자에게서 요구사항을 받아 기획자가 Notion 같은 문서에 정리하던 과정이, 아이디어를 낸 사람이 고객 문의나 CS 티켓을 들고 Claude와 대화하는 과정으로 바뀝니다. 이렇게 나온 intent.md는 사람이 읽는 문서이면서, 다음 단계가 따로 손보지 않고 바로 이어받을 수 있는 형식입니다. 플레이북은 첫 대화부터 intent.md가 커밋되기까지 걸린 시간을 이 단계의 지표로 삼고, 몇 주씩 걸리던 요구사항 수집과 정제 주기가 몇 시간으로 줄어들 것으로 봅니다.

설계: 넘길 때마다 생기던 해석 줄이기

예전에는 기획서를 디자이너가 읽고 Figma로 옮기고, 개발자는 그 Figma 디자인을 보고 다시 구현했습니다. 결과물을 다른 담당자에게 넘길 때마다 해석이 한 번씩 들어갔죠.

이제는 intent.md를 넘기면 Claude와 한 세션 안에서 요구사항과 설계 스펙을 뽑고, 프론트엔드 작업이라면 Claude Design 같은 도구로 목업까지 한 번에 만들 수 있습니다. 회사의 브랜딩이나 디자인 시스템 규칙은 오픈 표준인 스킬로 넣어 주고, 결과물은 git에 커밋하는 것으로 설계 단계가 끝납니다.

빌드: 병목은 팀 규칙을 AI가 아느냐로 이동

코드와 테스트를 에이전트가 만드니, 병목은 코드 작성이 아니라 우리 팀의 규칙을 AI가 잘 알고 있느냐로 옮겨갑니다. 빌드·테스트 명령, 팀 컨벤션, 아키텍처 구조는 CLAUDE.md나 AGENTS.md 같은 규칙 파일에 쌓아 두고, API를 구현할 때의 보안 리뷰 기준처럼 팀 전체에 똑같이 적용할 기준은 스킬로 만들어 두면 됩니다.

플레이북은 빌드의 출발점으로 Claude Code의 plan mode를 권합니다. plan mode에서 Claude는 코드베이스를 읽기만 하고 파일은 고치지 못합니다. 그래서 개발자가 계획을 받아들이기 전에는 코드가 바뀌지 않고, 방향을 바꾸는 일이 아직 문서 수정에 그칠 때 설계 리뷰가 끝납니다. 승인된 계획은 plan.md로 커밋돼 이후 단계가 대조하는 기준이 됩니다.

테스트: 에이전트가 스스로 하는 검증

예전에는 코드가 제대로 동작하는지 알려주는 신호가 늦게 왔습니다. CI(Continuous Integration, 코드 변경마다 빌드와 테스트를 자동으로 돌리는 체계) 결과는 몇 분 뒤, 테스터가 확인한 결과는 며칠 뒤에야 왔습니다. 에이전트가 코드를 쏟아내는데 신호가 늦으면 사람이 일일이 확인해야 하니 결국 사람이 병목이 됩니다.

이제는 Claude가 작업하는 동안 테스트 코드도 쓰고, 테스트를 돌리고, 빌드해 보고, UI 작업이면 브라우저를 띄워 스크린샷으로 목업과 비교하는 검증까지 하게 할 수 있습니다. 모든 검증이 통과할 때까지 고친 다음에야 사람이 확인하는 단계로 넘어가게 하네스를 세팅하는 겁니다. 이런 검증 루프를 어떻게 설계하는지는 Loop Engineering 글과도 이어집니다.

테스트 단계에서는 두 가지를 더 챙깁니다.

• TDD 규칙과 보호 훅: TDD(Test-Driven Development, 테스트 주도 개발)는 실패하는 테스트를 먼저 만들고, 그걸 통과하는 최소한의 코드를 쓰고, 마지막에 리팩토링하는 방식입니다. 이 규칙을 Claude에게 넣어 줄 수 있는데, 에이전트가 통과하려고 테스트 코드를 고쳐 버리는 경우가 생길 수 있습니다. 그래서 코드를 고치는 동안에는 테스트 파일을 편집하지 못하게 막는 보호 훅을 달아 둘 수 있습니다.
• 규칙과 스킬 변경도 테스트: Anthropic이 강조하는 부분입니다. 코드만 테스트하는 게 아니라 CLAUDE.md, 스킬, 훅 같은 설정이 바뀌었을 때도 에이전트가 여전히 같은 수준으로 일하는지 CI에서 확인하라는 겁니다.

플레이북의 예시 워크플로(.github/workflows/agent-evals.yml)에서 이름과 트리거 부분만 발췌하면 이렇습니다. CLAUDE.md나 .claude/ 아래 설정을 바꾸는 PR이 올라올 때, 그리고 매일 정해진 시각에 돕니다.

name: Agent evals
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**']
  schedule:
    - cron: '0 2 * * *'

트리거가 걸리면 잡은 미리 쌓아 둔 테스트 케이스 20~50개를 에이전트에게 다시 풀게 해서, 설정이 바뀐 뒤에도 같은 품질이 나오는지 봅니다. 예를 들어 최근 배포한 기능을 똑같이 구현시켜 보는 식입니다.

배포: 사람은 위험한 코드만 리뷰

에이전트 리뷰를 여러 겹 돌리려면 무엇을 볼지부터 글로 정해 둬야 합니다. 플레이북은 그 기준을 레포 루트의 REVIEW.md에 적는 방식을 예로 듭니다. 버그와 논리 오류, 보안 취약점, spec.md·plan.md 준수 여부처럼 관점을 나눠 리뷰를 돌리고, 모든 PR이 같은 리뷰를 거치게 하는 겁니다. 그러면 사람은 변경이 plan의 의도대로인지, 위험을 감수할 만한지에 집중할 수 있습니다.

보안이나 배포 정책 위반은 나중에 리뷰에서 잡는 게 아니라, AI가 파일을 고치거나 편집하는 바로 그 순간에 훅으로 잡아내게 할 수 있습니다.

운영: 감지는 결정론적으로, 기록은 레포로

예전에는 새벽에 오는 알림을 놓치기도 하고, 티켓이 쌓이면 백로그에 묻히고, 장애 회고에서 나온 재발 방지 작업은 다른 급한 불이 나면 코드까지 반영되지 못하는 경우가 대부분이었습니다. 이제는 이런 장치를 달 수 있습니다.

• 지표 감시 스크립트: CI 테스트 실패율, 배포 후 500 에러 발생량, PR 사이클 같은 지표를 주기적으로 보다가 기준을 넘으면 에이전트를 호출하게 합니다. 감지 로직은 LLM 없이 결정론적으로 짜고, 정도에 따라 로그만 남기거나 읽기 전용으로 진단만 하는 식으로 대응 단계를 절차적으로 높여 갑니다.
• 정기 보안 스캔: Claude Security 같은 도구를 달아 주기적으로 레포를 스캔하게 할 수 있습니다.
• Slack 첫 대응: Claude Tag로 Claude를 Slack 채널에 초대해 두면, 장애 해결 요청이 들어왔을 때 Claude가 1차로 PR을 만들어 대응하게 할 수 있습니다. 그 장애 회고도 마크다운 파일로 만들어 레포에 푸시하고, 회고 히스토리로 관리합니다.

단계마다 남는 결과물, 초안은 에이전트·승인은 사람

여섯 단계를 관통하는 원칙은 하나입니다.

Every stage commits an artifact the next stage can read.

각 단계는 다음 단계가 읽을 수 있는 결과물을 커밋한다.

단계별로 무엇이 남는지 보면 이렇습니다.

1. 계획: 의도를 정의한 intent.md
2. 설계: intent.md를 이어받아 만든 spec.md
3. 빌드: PO가 승인한 spec.md를 바탕으로 개발자가 plan mode에서 다듬은 plan.md
4. 테스트: 코드 diff와 그 diff를 검증하는 테스트
5. 배포: 리뷰 기록이 붙은 PR
6. 운영: 장애를 해결한 회고 문서

이 파일들을 전부 하나의 레포에 계속 쌓아 가는 구조가 핵심입니다. 플레이북은 승인이 다음 단계를 켜는 흐름으로 설명합니다. intent.md가 승인되면 요구사항과 설계가 시작되고, spec.md가 승인되면 plan mode가 켜지고, PR이 머지되면 파이프라인이 돌고, 운영에서 지표가 기준을 벗어나면 다음 intent.md가 만들어지면서 루프가 이어집니다. 처음부터 자동일 필요는 없고, 단계마다 손으로 시작해 이 루프로 가는 게 목표입니다.

각 파일의 초안은 에이전트가 만들고, 검토와 승인은 사람이 합니다.

Humans remain accountable for every decision that requires judgment.

판단이 필요한 결정은 전부 사람이 책임진다.

제가 더 중요하게 보는 건 이 부분입니다. 자동화되는 건 결과물의 초안이지, 책임이 아닙니다.

intent.md, spec.md, plan.md, CLAUDE.md는 어떻게 다른가

AI 네이티브 SDLC로 개발하는 시스템을 만들 때 주로 쓰는 파일은 네 종류입니다. 헷갈리기 쉬우니 한 표로 정리하겠습니다.

파일	답하는 질문	시작과 확정
CLAUDE.md, AGENTS.md	이 레포에서 AI가 알아야 할 규칙은 무엇인가	팀 전체가 관리, 변경은 코드처럼 PR로 리뷰
intent.md	이 기능을 왜 만드는가	아이디어를 낸 누구나 시작, PO가 승인
spec.md	그래서 무엇을 어떤 요구사항과 설계로 만드는가	intent 승인 뒤 생성, PO가 승인
plan.md	어떤 코드를 어떤 순서로 바꾸고 무엇으로 검증하는가	spec 승인 뒤 생성, 개발자가 다듬어 확정

의도를 먼저 정해야 하는 기능이라면 intent.md가 개발의 시작점입니다. 어떻게 보면 PRD나 스프린트 문서가 하던 역할을 어느 정도 대체할 수 있는 파일이죠.

intent와 spec을 PO가 승인하는 이유가 있습니다. 이 두 파일은 단순히 요구사항만 적는 게 아니라 회사 정책을 설계에 적용해야 하는 파일이라서, 코드만 아는 사람이 아니라 제품과 정책을 아는 PO가 맡아야 합니다. 반대로 plan.md는 코드를 작성하기 바로 직전 단계의 파일입니다. 코드베이스에 대한 맥락이 필요하니 개발자의 몫입니다.

팀 도입 구조: 레포 하나와 PR 승인 흐름

팀에 들일 때는 개발자 한 명을 정해, intent를 모으고 PO가 승인하는 시스템을 딱 한 번 설계해 두면 됩니다. 플레이북도 이 셋업을 플랫폼팀이나 엔지니어링팀이 한 번 하는 일로 보고, 기술 담당자가 intent를 모아 둘 곳을 만들고 누가 쓸 수 있는지 정하라고 합니다.

여기서 경계를 분명히 해 두겠습니다. Anthropic이 제안한 건 intent/ 폴더와 단계마다 결과물을 커밋하는 뼈대이고, 의도별 슬러그 폴더, 산출물 하나만 담은 PR, Slack 알림 같은 세부 구조는 제가 효율적이라고 생각해 정리한 것입니다. 원칙은 두 가지입니다.

• 도구를 최대한 늘리지 않습니다. 외부 도구는 GitHub, Slack, Claude 세 가지만 쓰고, Jira나 Confluence 같은 별도 도구는 쓰지 않는 구조입니다.
• 단일 진실 원천(SSOT, Single Source of Truth)을 지킵니다. 모든 지식의 원본을 한 곳에만 두는 원칙인데, AI를 쓸 때는 이게 무엇보다 중요해서 하나의 레포 안에서 전부 동작하게 했습니다.

Anthropic도 레포를 원본으로 두는 구성이 엔지니어링 주도 조직에서는 가장 깔끔한 구성 중 하나가 될 수 있다고 봅니다.

Slack 태그에서 feature PR까지

새 엔지니어링 조직을 설계하거나 기존 개발 라이프사이클을 AI 네이티브로 전환해 보고 싶다면 참고할 수 있게, 전체 흐름을 정리해 봤습니다.

1. Slack에서 Claude나 팀이 쓰는 에이전트를 태그해 의도를 설명합니다. 기획자나 CS 담당자의 요청뿐 아니라 버그 티켓이나 장애 로그도 intent의 소스가 됩니다. 손으로 돌리는 게 익숙해지면 티켓 등록, Slack 호출, 지표 이탈 같은 이벤트가 생길 때 에이전트가 진단해 사람 없이 초안을 만들게 할 수 있습니다.
2. 에이전트가 intent.md 초안을 만들고, intent/<슬러그> 브랜치에서 intent.md 하나만 담은 PR을 GitHub에 올립니다.
3. PO가 그 PR을 검토하고 머지합니다. 머지가 곧 승인이고, 반려라면 머지하지 않고 PR을 닫습니다.
4. 머지되면 CI 잡이 자동으로 돌면서 spec.md 초안을 만들고, spec/<슬러그> 브랜치에서 spec.md 하나만 담은 PR을 올립니다.
5. PO가 spec PR도 검토하고 머지합니다. 플레이북은 조직이 위험도가 높다고 분류한 변경이라면 이때 기술 리드와 상의하라고 권합니다.
6. spec이 머지되면 담당 개발자에게 Slack으로 GitHub 멘션 알림이 갑니다.
7. 개발자는 intent와 spec 두 문서를 바탕으로, 로컬에서 Claude Code나 Cursor, Codex 같은 코딩 에이전트로 plan.md 초안을 만듭니다. 그 초안에 코드베이스 구조와 아키텍처 맥락을 반영해 plan.md를 완성합니다.
8. 에이전트가 plan을 따라 코드를 생성하고, 테스트하고, 검증을 마치면 feature/<슬러그> 브랜치로 PR을 올립니다. 코드 리뷰를 받고 머지하면 한 바퀴가 끝납니다.

이 중 머지를 승인으로 보는 것과, intent 머지에 반응하는 잡이 spec.md를 PR로 올리는 것은 Anthropic의 설명과도 맞습니다. 플레이북은 intent를 설계로 넘길지 말지가 PR 머지나 리뷰 종료로 기록된다고 하고, PO가 설계 단계로 받아들인 intent.md의 비율도 지표로 봅니다.

폴더 구조: 의도 하나에 폴더 하나

제 프로젝트에 실제로 적용한 구조는 이렇습니다. 프로젝트 루트의 intent/ 폴더에 README.md를 두고, 그 아래에 변경마다 슬러그 폴더를 하나씩 만들어 intent, spec, plan 세 파일을 넣습니다. 앞의 배송 예시라면 슬러그는 ship-tracking처럼 짓습니다.

intent/
  README.md          # 폴더 규칙, source of truth 표
  ship-tracking/     # 변경 하나당 폴더 하나
    intent.md        # 왜 만드나 (PO 승인)
    spec.md          # 무엇을 어떤 요구·설계로 (PO 승인)
    plan.md          # 어디를 어떤 순서로, 무엇으로 검증 (개발자)
  <다른-기능-슬러그>/
    ...

README.md에는 폴더 규칙과 source of truth 표, 즉 결과물마다 원본이 어디 있는지를 적어 둡니다. 레포 하나를 원본으로 삼는 SSOT 원칙을 문서로 고정해 두는 파일입니다.

여기서 중요한 규칙이 하나 있습니다. 폴더 하나에 intent, spec, plan은 하나씩만 둡니다. 만약 한 폴더 안에 spec이 두 개 필요해진다면, 그건 intent 하나에 spec을 늘릴 게 아니라 애초에 intent를 두 개로 나눠야 하는지를 판단해 봐야 한다는 신호입니다.

아주 큰 기능이라도 spec을 여러 개로 쪼개기보다, 기능 자체를 작은 단위로 나눠 개발하는 편이 의도를 더 효율적으로 관리할 수 있다고 봅니다. Anthropic도 spec.md를 intent.md 옆에 커밋해, 두 파일이 한 쌍으로 무엇을 요청했고 무엇을 결정했는지 기록하게 합니다.

언제 쓰고 언제 생략하나: 단계적으로 도입하기

기존 조직에는 레거시 개발 프로세스의 잔재가 많이 남아 있을 수 있습니다. 그걸 한 번에 다 바꾸려고 하면 사실 어렵습니다. 그래서 필요한 것부터 하나씩 단계적으로 들이는 게 좋습니다. 플레이북도 대부분의 조직은 기존 방식과 AI 네이티브 방식 사이 어딘가에 있고, 단계마다 따로 바꿔도 된다고 설명합니다.

판단 기준은 이렇게 잡아 보면 좋겠습니다.

상황	권장
오탈자 수정, 작은 버그, 할 일이 명확한 작업	intent 없이 바로 수정
혼자 개발하는 경우	큰 기능 단위를 시작할 때만 intent를 먼저 작성
팀에서 큰 기능을 시작하는 경우	intent부터 남기고 spec, plan으로 이어가기
Jira 같은 외부 서비스를 쓰는 조직	결과물마다 원본이 어디 있는지 링크부터 걸기

Jira 같은 외부 서비스를 이미 쓰는 조직이라면 앞의 레포 하나 구조를 고집할 필요는 없습니다. 마크다운 결과물에는 Jira 레코드 ID를, Jira 레코드에는 그 마크다운 파일의 커밋 SHA를 적어 서로 연결하는 것만으로 작게 시작할 수 있습니다. Anthropic도 원본이 두 곳이 되는 걸 감수하더라도 이 연결 방식이 전환의 좋은 출발점이라고 봅니다.

플레이북 자체도 Anthropic에서 기업 고객의 AI 도입을 돕는 Applied AI 팀이 고객사를 위해 매일 실행하는 모범 사례를 모은 가이드입니다. 그래서 정답 하나를 외우기보다, 우리 팀에서 어디가 막히는지부터 보고 그 단계에 맞는 파일과 승인 절차를 골라 들이는 게 맞다고 봅니다.

정리: intent.md로 의도부터 남기기

정리하면 두 가지입니다. 하나는 AI로 개발하면서 의도를 전달하는 일이 훨씬 중요해졌다는 것입니다. 다른 하나는 기존 개발 라이프사이클과 달리 모든 단계에서 AI가 초안을 만들고, 사람은 판단이 필요한 부분만 승인하는 시스템을 만드는 게 중요해지고 있다는 것입니다.

의도를 쌓는 구조를 잘 만들어 두면, AI로 많은 코드를 만들더라도 그 코드를 리뷰할 때 의도를 해석하는 단계를 줄일 수 있습니다. 그래서 저는 Anthropic이 제안한 intent.md의 방향 자체는 굉장히 훌륭하다고 봅니다.

여러분도 큰 기능 하나를 앞두고 있다면 바로 구현시키지 말고, 왜 만드는지부터 intent.md로 남겨보세요. 플레이북 맺음말의 마지막 문장으로 마무리하겠습니다.

The loop keeps running. Human judgement stays above it.

루프는 계속 돈다. 사람의 판단은 그 위에 남는다.