intent.md와 AI 네이티브 SDLC: 1인 개발에 적용할 문서와 승인 기준

9월 초에 코드 작성 전에 intent.md를 쓰라는 해설 영상을 클립해뒀다. 나는 이미 기획서와 스펙을 쓰고 있어서 문서 하나를 더 만드는 이유가 궁금했다. 원출처는 Louis Claxton이 2026년 8월 21일 공개한 Anthropic의 AI 네이티브 SDLC 플레이북이었다.

읽으면서 내 작업에 적용할 질문을 좁혔다. 다음 에이전트가 무엇을 읽어야 하는가. 사람은 어느 버전을 승인했는가. 구현이 끝났다는 말을 어떤 검사로 확인하는가. 이 글은 공식 제안의 개요와 내 적용안을 구분한 문서 분석이다. 플레이북 전체를 운영해 생산성을 측정한 후기는 아니다.

공식 제안에서 확인한 범위

플레이북은 계획·설계·구현·테스트·배포·유지보수의 여섯 단계를 다룬다. 다음 단계가 읽을 수 있도록 산출물을 버전 관리하고, 운영 중 발견한 문제를 새로운 의도로 돌려보내는 구성을 제안한다. 구현 속도가 빨라져도 앞뒤의 검토와 인계가 늦으면 전체 흐름이 막힌다는 설명이다. 모든 조직에서 코딩 병목이 사라졌다고 입증한 연구 결과로 읽지는 않았다.

계획 단계의 intent.md에는 문제, 기대 결과, 영향받는 사용자와 시스템, 제약, 미해결 질문을 담는 템플릿을 제시한다. 조직이 합의할 수 있는 형식의 예시다. 에이전트가 초안을 만들더라도 책임자가 오해를 고치고 다음 단계로 넘길지 판단한다. 이후에는 스펙과 구현 계획뿐 아니라 코드·테스트, PR 검토 결과, 장애 기록도 남긴다. 이 개요는 위 공식 플레이북에 근거한다.

나는 여기서 파일 이름보다 인계 조건을 가져오려 한다. 모든 작업에 다섯 칸을 강제하거나 문서 여섯 개를 복제할 필요는 없다. 내 저장소에서 같은 질문에 답하는 문서가 있다면 그 문서를 원본으로 정하고 다음 단계가 참조하게 하면 된다. 아래 템플릿과 점검표는 이 목적에 맞춰 만든 내 적용안이며 Anthropic 표준 양식의 전재가 아니다.

intent.md와 CLAUDE.md를 혼동하지 않는다

intent.md를 폴더에 두는 것만으로 에이전트가 읽었다고 판단할 수 없다. Claude Code의 메모리 문서는 CLAUDE.md 같은 지침 파일의 로딩 방식과 외부 파일 참조를 설명한다. 개발 목적을 담은 일반 Markdown 파일과 도구가 인식하는 지침 파일은 역할이 다르다. 내 작업에서는 시작 요청에 현재 작업의 의도 파일 경로를 명시하는 방법부터 쓸 수 있다.

이번 작업의 목적과 제외 범위는 intent/news-filter.md를 읽어줘.
구현 전에 확정한 조건과 아직 답이 필요한 질문을 구분해줘.
현재 단계는 설계 검토이며 파일 수정·배포 승인은 포함하지 않아.

이 문구는 사용 예시다. 이번 글을 쓰면서 실제 개발 환경의 설정이나 스킬을 변경한 것은 아니다. 반복해서 필요하다면 작업 진입 문서에 읽기 절차를 적겠지만, 진행 중인 모든 의도 파일을 매번 전부 넣지는 않을 생각이다. 완료한 실험의 제약을 다음 프로젝트의 규칙으로 오해할 수 있기 때문이다.

지침을 읽는 것과 행동을 강제하는 것도 구분한다. 메모리 문서는 지침을 컨텍스트로 취급하며 강제 설정과 다르다고 설명한다. “승인 전 배포 금지”라는 문장을 썼어도 실제 배포 자격을 가진 프로그램이 다른 경로로 실행될 수 있다. 문서에는 목적과 정책을 적고, 실행 권한은 도구와 배포 절차에서도 검사해야 한다.

기존 네 문서에 연결하되 같은 내용을 복사하지 않는다

나는 스펙 주도 개발 글에서 BRIEF·SPEC·PLAN·STATE를 나눠 쓰는 방식을 정리했다. intent.md를 도입하더라도 BRIEF의 목적과 제약을 그대로 복사한 파일을 하나 더 유지할 이유는 적다. 한쪽만 바뀌면 에이전트가 어느 문서를 믿어야 할지 다시 물어야 한다.

내 문서	이 문서에서 확정할 질문	다음 단계에 넘길 근거
BRIEF 또는 intent	누구의 어떤 문제를 풀고 무엇은 하지 않는가	목적·제약·열린 질문을 검토한 버전
SPEC	사용자가 관찰할 동작과 실패 처리는 무엇인가	요구사항 ID와 수용 조건
PLAN	어떤 순서로 어디를 바꾸고 검사하는가	파일 범위·시험·복구 계획
STATE	지금 무엇을 완료했고 무엇이 남았는가	실행 기록·결정 변경·다음 시작점

이 표는 내 대응 방식이다. STATE 하나가 테스트 결과나 배포 기록을 모두 대신한다는 뜻은 아니다. STATE에는 그 증거가 있는 위치를 적는다. 테스트 이름과 실행 결과, 배포 ID와 운영 확인 결과가 따로 있으면 다음 작업자가 확인할 수 있다.

기존 글에서 다룬 GSD의 단계 구분도 이 표와 연결할 수 있지만 두 프레임워크가 동일하다고 단정할 필요는 없다. 나는 새 방법을 읽을 때 이미 가진 문서로 표현할 수 있는 부분부터 찾는다. 목적을 새로 쓰는 것과 현재 결정이 바뀌었다는 사실을 기록하는 일은 구분해 유지한다.

문서가 짧아져도 제외 범위는 남겨야 한다. “뉴스 필터 개선”만 쓰면 수집기 교체, 요약 모델 변경, 자동 발송까지 한 작업으로 확대될 수 있다. “이번 실험은 선별 결과를 기록하는 데 한정하고 발송은 바꾸지 않는다”라고 적으면 검토자가 범위 밖 변경을 찾기 쉽다.

뉴스 필터 실험으로 다섯 질문을 채워 보기

아래는 Jev 도입 실험 글과 연결한 예시다. API 실행 결과나 확정된 개발 일정이 아니다. 비교할 문제와 아직 결정하지 않은 항목을 한곳에 적어 보는 적용안이다.

# 아침 뉴스 선별 비교 실험
상태: 초안 / 실행 승인 전
담당: CK

## 문제
현재 선별에서 놓치는 기사가 있는지와 검토 부담을 확인하고 싶다.
전체 수집 건수와 탈락 경로의 기준선을 먼저 기록한다.

## 기대 결과
같은 기사 묶음에서 기존 방식과 판단 모델의 선택 결과를 비교한다.
중요 기사 누락, 불필요한 추천, 비용과 검토 시간을 함께 본다.
자동 제외를 켜는 것은 이번 단계의 목표가 아니다.

## 영향 범위
daily-digest의 선별 단계와 비교 로그.
수집 대상, 요약 생성, 구독자 발송 경로는 변경하지 않는다.

## 제약
접근 권한과 비용 한도를 확인한 뒤 API를 호출한다.
비밀 값과 비공개 자료는 외부 판단 입력에서 제외한다.
실패하면 기존 선별 결과를 유지한다.
기존 원본과 비교 기록을 덮어쓰지 않는다.

## 열린 질문
사람이 관련성을 판정할 기준과 비교 표본은 무엇인가?
판단이 모호한 기사를 어느 검토함에 보낼 것인가?
누락과 수동 검토 시간의 허용 범위는 얼마인가?

문제 설명부터 측정과 추정을 나눈다. 현재 필터가 실제로 어떤 기사를 버리는지 확인하지 않은 상태에서 “나머지는 전부 검사 없이 버린다”고 확정하면 개선 대상부터 잘못 잡을 수 있다. 수집, 중복 제거, 키워드 선별, 모델 입력의 각 단계에 몇 건이 남는지 먼저 확인할 계획이다.

기대 결과에도 성과를 약속하지 않는다. 비용 감소와 누락 감소는 동시에 달성하기 어려울 수 있다. 확인할 지표를 적고 허용할 손실은 미해결 질문에 남긴다. 답을 정하기 전에는 기존 결과 옆에 비교 결과만 기록하는 그림자 실행으로 범위를 제한할 수 있다.

“낮은 신뢰도는 버릴까”라는 질문도 구체화해야 한다. 뉴스 추천과 삭제 명령은 오판 비용이 다르다. 기사라면 사람이 보는 보류 목록에 둘 수 있다. 외부 쓰기라면 승인이 없거나 판단 근거가 부족할 때 실행을 멈추는 경로가 필요하다. 숫자 임계값 하나를 모든 작업에 공통으로 쓰지는 않을 생각이다.

열린 질문이 남아 있어도 할 수 있는 일을 분리한다

문서에 질문을 적었다고 그 질문이 해결되지는 않는다. 다음 에이전트가 정확한 후속 질문을 한다고 보장할 수도 없다. 내 작업에서는 질문마다 답이 필요한 시점과 그전까지 허용할 범위를 붙이는 편이 낫다.

예를 들어 비교 표본을 아직 정하지 못했어도 로그 형식을 설계할 수 있다. 외부 전송 가능 범위가 정해지지 않았다면 실제 원고를 API로 보내는 실험은 멈춰야 한다. 결정을 기다리는 동안 가상 데이터로 파서와 실패 처리만 검사할 수 있다. 이 구분이 없으면 모든 일을 멈추거나 반대로 승인 없이 추측해서 진행하게 된다.

열린 질문	답변 전 가능한 작업	답변 없이는 멈출 작업
관련성 기준	후보 기준과 판정 예시 작성	운영 자동 제외
외부 전송 범위	가상 입력으로 형식 검사	비공개 데이터 전송
비용 한도	사용량 기록 구조 설계	유료 반복 실행
공개 승인 대상	검수용 초안 생성	배포와 외부 발송

이 표는 위 뉴스 실험을 나눠 진행하기 위한 예시다. 실제 승인 권한을 만들지 않는다. 담당자가 답한 뒤에는 답변을 원본 문서에 반영하고, 새 조건이 SPEC이나 PLAN에 영향을 주는지도 확인해야 한다.

승인한 버전과 실행할 버전을 연결한다

에이전트가 좋은 계획을 쓴 뒤 구현 과정에서 범위를 바꿀 수 있다. 검토자가 처음 계획에 동의했다는 이유로 나중의 모든 변경까지 승인했다고 보면 안 된다. 데이터 삭제, 외부 발송, 공개 배포는 변경된 내용과 대상이 무엇인지 다시 확인해야 한다.

내 적용안에서는 작업 ID에 의도 파일의 커밋, 검토한 계획, 실제 diff와 검사 결과를 연결한다. 승인 후 구현 대상이 바뀌면 기존 승인 상태를 그대로 이어 쓰지 않고 영향을 표시한다. 문장을 고친 정도와 외부 행동을 바꾼 정도는 구분하되, 그 구분을 구현자의 편의로만 정하지 않는다.

작업: 뉴스 선별 비교
승인 범위: 저장된 가상 입력으로 선별 결과 기록
미승인 범위: 운영 구독자 발송, 기존 기사 삭제, 유료 반복 호출
확인할 증거: 입력 버전, 판단 로그, 실패 시 기존 경로 유지 시험
범위 변경 시: 계획과 승인 대상 재검토

이 예시는 내가 새로 적용하려는 승인 기록 형식이다. 실제 승인을 받았다는 보고가 아니다. 커밋 해시를 붙이면 어떤 문서를 봤는지는 추적할 수 있지만 승인자의 신원이나 배포 권한을 자동으로 증명하지는 않는다. Git 기록과 실제 권한 설정을 함께 관리해야 한다.

훅과 검사는 실행 위치를 확인한다

Claude Code 훅 안내는 도구 실행 전 검사인 PreToolUse와 실행 후 처리의 차이를 설명한다. 실행 후 훅으로 이미 일어난 외부 쓰기를 없앨 수는 없다. 특정 도구에만 연결한 검사라면 다른 도구 호출까지 막았다고 생각해서도 안 된다.

내 블로그에는 이미 원고 메타데이터 검사와 배포 확인 절차가 있다. intent 문서를 추가한다고 이 검사를 나중으로 미룰 이유는 없다. 목적 문서는 검토자가 왜 바꾸는지 이해하도록 돕고, 자동 검사는 정해 둔 조건을 어겼는지 확인한다. 두 역할을 겹쳐 놓아야 한다.

검사를 통과했다는 말도 범위를 적는다. 빌드 성공은 코드가 배포 가능한 형태로 만들어졌다는 증거다. 운영 URL의 본문이 바뀌었다는 증거는 별도로 확인한다. DB 저장 성공만으로 정적 원고를 사용하는 대표 페이지까지 바뀌었다고 결론 내리지 않는다. 이 블로그의 문서와 DB가 서로 다른 경로를 거치는 만큼 중요한 구분이다.

훅 자체의 실패도 시험 대상으로 남길 생각이다. 검사 프로그램이 설치되지 않았거나 입력 형식이 바뀌면 어떤 일이 생기는지 확인한다. 위험한 외부 쓰기에서는 검사 실패가 허용으로 이어지지 않게 설계하고, 정상 요청과 금지 요청을 각각 테스트한다. 이 글의 적용안에서는 모델에게 안전한지 묻는 호출 하나로 권한 검사를 대체하지 않는다.

1인 개발에서 문서를 늘릴 기준

작은 오타 수정은 파일 위치와 기대 문장, 확인 결과만 남겨도 충분할 수 있다. 사용자 행동을 바꾸거나 여러 세션에 걸치는 작업이라면 목적과 제외 범위를 적는다. 데이터를 옮기거나 외부에 공개하는 작업에서는 복구와 승인 기록까지 필요하다. 문서 수를 작업 규모의 목표로 삼지는 않는다.

이미 BRIEF가 있다면 열린 질문과 제외 범위가 빠지지 않았는지 먼저 확인하려 한다. SPEC과 PLAN이 같은 내용을 반복한다면 한쪽에 원본을 두고 다른 쪽은 참조하도록 정리한다. 개인 프로젝트라도 누가 판단했는지와 어떤 증거로 완료했는지는 남긴다. 담당자가 나 혼자라는 이유로 책임 기록이 없어지는 것은 아니다.

적용 효과는 다음 작업 몇 건의 기록으로 확인할 수 있다. 계획을 다시 쓰게 만든 질문, 구현 뒤 발견한 범위 변경, 다음 세션에서 반복한 질문을 남긴다. 문서 작성 시간만 늘고 재작업이나 인계 문제가 줄지 않으면 양식을 줄여야 한다. 반대로 자주 빠지는 제약은 진입 문서나 검사 항목에 반영한다.

나는 뉴스 필터 비교처럼 목적은 정해졌지만 성공 기준과 실행 범위가 더 필요한 작업부터 이 형식을 써보려 한다. 다음 세션에 넘길 것은 목적, 현재 결정, 아직 승인하지 않은 행동과 확인할 증거다. 그 내용을 기존 문서로 전달할 수 있다면 새 이름의 파일을 추가하지 않아도 된다.

참고자료

관심을 갖게 된 해설 영상은 AI 네이티브 SDLC 도입 정리다. 기술 설명은 위 공식 자료를 기준으로 검토했으며, 이 글의 뉴스 실험 템플릿은 별도로 작성한 적용안이다.

읽기 전 요약