이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
클로드 코드 개발 워크플로 7단계, intent.md부터 배포까지
앤트로픽 Applied AI 팀이 공개한 AI 네이티브 개발 방식을 7단계 클로드 코드(Claude Code) 개발 워크플로로 풀어 설명합니다. 요구사항을 적는 intent.md에서 시작해 spec.md, plan.md를 거쳐 만들기, 테스트, 배포, 유지보수까지 각 단계에서 무엇을 하고 어떤 문서를 남기는지 개발 용어를 풀어 가며 따라갑니다.

"Code is no longer the bottleneck."(이제 코드는 병목이 아니다.) 앤트로픽 Applied AI 팀이 2026년 8월 claude.com 블로그에 공개한 AI-native SDLC 플레이북의 첫 장 제목입니다. 병목은 전체 흐름 중 가장 느려서 나머지를 붙잡는 구간을 말합니다. 에이전트(지시를 받으면 스스로 여러 단계를 이어서 처리하는 AI)가 빌드(실제로 코드를 짜서 만드는 일) 단계를 몇 시간 단위로 줄이면서, 병목은 기획·설계·테스트·배포·유지보수 쪽으로 옮겨 갔습니다.
이 방식은 intent.md라는 파일 하나에서 시작해 spec.md → plan.md로 이어지는 문서 3종과, 그 뒤를 잇는 build → test → deploy → maintain 4단계로 이뤄집니다. 끝이 .md인 파일은 마크다운 파일로, 제목과 목록 정도의 서식만 있는 텍스트 문서입니다. 메모장으로도 열립니다.
시작 전 준비: 클로드 코드와 작업 폴더
이 워크플로는 몇 가지가 이미 갖춰져 있다고 보고 진행합니다. 처음이라면 아래부터 준비합니다.
- 클로드 코드를 설치합니다. 클로드 코드는 터미널에서 대화하듯 시키면 코드를 읽고 고치는 클로드입니다. 설치 방법은 앤트로픽 공식 문서를 따릅니다.
- 터미널을 엽니다. 맥은 응용 프로그램 > 유틸리티 > 터미널, 윈도우는 시작 메뉴에서 PowerShell을 검색해 엽니다.
cd 프로젝트폴더경로를 입력해 작업할 폴더로 이동합니다. 폴더를 터미널 창에 끌어다 놓으면 경로가 자동으로 입력됩니다. claude를 입력하고 Enter를 누르면 클로드 코드가 시작됩니다.
build 단계부터는 git(파일 변경 이력을 기록하고 되돌릴 수 있게 해 주는 도구) 저장소가 있다고 가정합니다. 저장소는 git이 이력을 관리하는 프로젝트 폴더입니다.
1. Intent: 대화로 요구사항을 뽑는다
에이전트에게 만들고 싶은 기능이나 고칠 버그를 설명하면, 에이전트가 되묻는 질문에 답하는 방식으로 진행됩니다. 자체 되묻기 스킬(클로드에게 특정 작업 절차를 미리 적어 준 설명서 묶음)이 없다면 Matt Pocock의 "grill me", Cursor의 "requirements discovery" 같은 discovery skill을 대신 씁니다. discovery skill은 사용자에게 질문을 던져 원하는 것을 끌어내도록 만든 스킬입니다.
처음 해 본다면 이렇게 따라 합니다.
- 클로드 코드에 만들고 싶은 기능이나 고칠 버그를 평소 말투로 설명합니다.
- 클로드가 되묻는 질문에 하나씩 답합니다.
- 충분히 정리됐다 싶으면 대화 내용을 intent.md로 정리해 달라고 요청합니다.
- 프로젝트 최상위
intent/폴더에 저장하게 합니다. - 저장된 intent.md를 끝까지 읽고 잘못된 부분을 직접 고칩니다.
작성자(originator, 요청을 처음 낸 사람)는 전문가가 아니어도 됩니다. 고객, PM(제품 기획·관리 담당자), 개발자 누구든 가능합니다. 다만 originator 본인이 intent.md를 끝까지 읽고 잘못된 부분을 직접 고쳐야 합니다. intent가 쌓이면 Notion·
2. Spec: 정해진 프롬프트로 자동 생성
spec은 요구사항과 설계를 구체적으로 적은 명세서입니다. intent.md가 확정돼 저장소에 합쳐지면(머지), 그때 도는 자동 작업(CI)이 spec 생성을 시작시킵니다. CI는 코드가 올라올 때마다 정해 둔 검사·작업을 자동으로 돌리는 장치입니다. 공개된 프롬프트(AI에게 주는 지시 문장) 원문은 이렇습니다.
read the attached intent MD and produce a requirements and design spec.
Apply skills available to you to plan and conform to brand guidelines
and then document the spec fully in spec.md.
"첨부된 intent.md를 읽고 requirements와 design spec을 만들고, 브랜드 가이드라인을 준수해 spec.md에 문서화해 줘"라는 뜻입니다. 이 문구를 꼭 그대로 써야 하는 건 아닙니다. plan mode(바로 고치지 않고 계획부터 세워 보여 주는 클로드 코드의 모드)를 그대로 쓰거나 팀 전용 skill을 만들어도 됩니다. 다만 agents.md나 skill에 정의된 조직 스타일 가이드가 반영되는지는 확인해야 합니다. agents.md는 AI 에이전트가 이 프로젝트에서 지켜야 할 규칙을 적어 두는 파일입니다.
3. Plan: 다른 사람도 볼 수 있는 계획서
intent.md와 spec.md를 함께 plan mode에 넣어 plan.md를 만듭니다. "이 변경으로 무엇이 깨질 수 있는가"를 되물어 검증하고, plan.md만 보고도 다른 엔지니어가 구현할 수 있는 수준인지 확인합니다. build 단계부터는 새 context window의 독립 서브에이전트가 이어받기 때문입니다. context window는 AI가 한 번에 기억하고 참고할 수 있는 대화 분량이고, 서브에이전트는 큰 작업의 일부를 따로 맡는 보조 AI입니다. 앞의 대화를 모르는 채로 시작하니, 계획서만으로 일이 이어져야 합니다.
plan.md에는 변경 파일 목록, 작업 순서, 리스크·제약, 성공 기준(proof)이 들어가야 합니다. 버전과 수정 이력도 거버넌스(누가 언제 무엇을 결정했는지 추적하는 관리 체계) 목적으로 저장해 둡니다.
4. Build: 권한을 조인 뒤 자동화
권한이 사전에 조여진 저장소에서 auto mode(매번 허락을 묻지 않고 알아서 진행하는 모드)를 쓰는 걸 권장합니다. 여러 작업은 git worktree로 나눠 병렬 진행합니다. git worktree는 한 저장소를 여러 작업 폴더로 갈라 동시에 다른 작업을 하게 해 주는 git 기능입니다. hook으로는 구현 완료 시 plan 자동 업데이트, 특정 폴더 접근 차단, 미승인 npm 패키지(자바스크립트 프로젝트에 가져다 쓰는 외부 코드 묶음) 업그레이드 차단을 걸어 둡니다.
5. Test: 작성부터 회귀 검증까지
에이전트가 테스트를 작성하고 린트(코드가 정해진 규칙에 맞는지 자동으로 검사하는 것)·빌드로 오류를 확인합니다. 더 나아가려면 Playwright·
6. Deploy: 사람 리뷰 뒤 에이전트 리뷰가 한 번 더
배포는 만든 결과를 실제 사용자가 쓰는 서비스에 반영하는 일입니다. 사람이 최종 리뷰를 한 뒤, 에이전트가 자기 브랜치(원본을 건드리지 않고 따로 갈라 작업하는 줄기)에서 만든 변경으로 pull request를 만듭니다. pull request는 "이 변경을 원본에 합쳐 달라"고 검토를 요청하는 절차입니다.
Claude가 정책·보안 프로토콜 기준으로 비동기 리뷰를 달면, 별도 Claude Code 인스턴스(따로 실행한 또 하나의 클로드 코드)가 그 코멘트를 다시 확인합니다. 승인·릴리즈 일정 조건이 충족되기 전엔 배포를 막는 hook을 걸 수 있습니다. PR 완료 후엔 bugbot·
7. Maintain: 진단이 먼저 끝나 있다
장애·신규 티켓(처리할 문제나 요청을 적은 업무 카드)·
클로드 코드 개발 워크플로를 관통하는 원칙
전체를 관통하는 원칙은 하나입니다. 워크플로를 표준화하고 자주 바꾸지 않습니다. superpowers, BMAD 같은 기존 워크플로(공개된 에이전트 개발 절차 모음)가 있다면 전면 교체할 필요 없이 참고해서 취사선택하면 됩니다. 목표는 SDLC(기획부터 유지보수까지 소프트웨어 개발 전 과정) 전 단계에 에이전트를 넣어 사람 개입 시간을 줄이되, 중요한 검토 지점에는 사람을 남겨 두는 데 있습니다.
자주 묻는 질문
intent.md, spec.md, plan.md는 각각 무엇이 다른가요?
intent.md는 무엇을 왜 만들고 싶은지 대화로 뽑아 적은 요구 문서입니다. spec.md는 그 요구를 바탕으로 요구사항과 설계를 구체적으로 풀어 쓴 명세서입니다. plan.md는 바꿀 파일, 작업 순서, 위험 요소, 성공 기준까지 담아 다른 사람이나 새 에이전트가 그대로 구현할 수 있게 만든 실행 계획서입니다.
클로드 코드 개발 워크플로는 개발자가 아니어도 쓸 수 있나요?
첫 단계인 intent는 누구나 맡을 수 있습니다. 고객이나 기획자도 에이전트의 질문에 답하고 intent.md를 읽고 고치면 됩니다. 다만 build 이후 단계는 git 저장소, 테스트, 배포 환경이 갖춰져 있어야 하므로 개발 환경을 다룰 사람이 함께 있어야 합니다.
클로드 코드의 hook은 무엇이고 어디에 쓰나요?
hook은 특정 순간이 오면 정해 둔 동작을 자동으로 실행하는 설정입니다. 이 방식에서는 주로 안전장치와 승인 단계에 씁니다. 구현이 끝나면 plan을 업데이트하고, 허락 안 된 패키지 업그레이드나 조건이 안 맞는 배포를 막습니다. spec 생성을 시작시키는 것은 hook이 아니라 intent.md 머지 때 도는 자동 작업(CI)입니다.
에이전트에게 배포까지 맡겨도 괜찮은가요?
이 방식도 전부 맡기지는 않습니다. 사람이 최종 리뷰를 한 뒤에 pull request가 만들어지고, 승인과 릴리즈 일정 조건을 채우기 전에는 hook으로 배포를 막습니다. 사람 개입 시간은 줄이되 중요한 검토 지점에는 사람을 남겨 두는 것이 원칙입니다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗