클로드 코드 개발 워크플로 7단계, intent.md부터 배포까지

Claude Code(클로드 코드) 팀이 공개한 AI 네이티브 개발 방식을 7단계 클로드 코드 개발 워크플로로 정리했습니다. 요구사항을 적는 intent.md에서 시작해 spec.md, plan.md를 거쳐 만들기, 테스트, 배포, 유지보수까지 각 단계에서 무엇을 하고 어떤 문서를 남기는지, 개발 용어를 풀어 가며 설명합니다.

"Code is no longer the bottleneck. It's your process."(이제 코드는 병목이 아니고, 문제는 일하는 과정이다.) Anthropic(자막 표기 흔들림, 글 끝 참고) Claude Code 팀이 공개한 AI-Native 개발 방식 문서를 리뷰한 영상 속 문장입니다. 병목은 전체 흐름 중 가장 느려서 나머지를 붙잡는 구간을 말합니다. 에이전트(지시를 받으면 스스로 여러 단계를 이어서 처리하는 AI)가 빌드(실제로 코드를 짜서 만드는 일) 단계를 대폭 줄이면서(자막상 "2배 빠름") 병목은 기획·설계·테스트·배포·유지보수 쪽으로 옮겨갔습니다.

이 영상은 intent.md라는 파일 하나에서 시작해 spec.md → plan.md로 이어지는 문서 3종과, 그 뒤를 잇는 build → test → deploy → maintain 4단계를 소개합니다. 끝이 .md인 파일은 마크다운 파일로, 제목과 목록 정도의 서식만 있는 텍스트 문서입니다. 메모장으로도 열립니다.

시작 전 준비: 클로드 코드와 작업 폴더

이 방식은 몇 가지가 이미 갖춰져 있다고 보고 설명합니다. 처음이라면 아래부터 준비합니다.

1. 클로드 코드를 설치합니다. 클로드 코드는 터미널에서 대화하듯 시키면 코드를 읽고 고치는 클로드입니다. 설치 방법은 앤트로픽 공식 문서를 따릅니다.
2. 터미널을 엽니다. 맥은 응용 프로그램 > 유틸리티 > 터미널, 윈도우는 시작 메뉴에서 PowerShell을 검색해 엽니다.
3. cd 프로젝트폴더경로를 입력해 작업할 폴더로 이동합니다. 폴더를 터미널 창에 끌어다 놓으면 경로가 자동으로 입력됩니다.
4. claude를 입력하고 Enter를 누르면 클로드 코드가 시작됩니다.

build 단계부터는 git(파일 변경 이력을 기록하고 되돌릴 수 있게 해주는 도구) 저장소가 있다고 가정합니다. 저장소는 git이 이력을 관리하는 프로젝트 폴더입니다.

1. Intent — 대화로 요구사항을 뽑는다

에이전트에게 만들고 싶은 기능이나 고칠 버그를 설명하면, 에이전트가 되묻는 질문에 답하는 방식으로 진행됩니다. 자체 되묻기 스킬(클로드에게 특정 작업 절차를 미리 적어 준 설명서 묶음)이 없다면 "switch dimension discovery", Matt PCO의 "grill me", Cursor의 "requirements discovery" 같은 discovery skill을 대신 씁니다. discovery skill은 사용자에게 질문을 던져 원하는 것을 끌어내도록 만든 스킬입니다.

처음 해본다면 이렇게 따라 합니다.

1. 클로드 코드에 만들고 싶은 기능이나 고칠 버그를 평소 말투로 설명합니다.
2. 클로드가 되묻는 질문에 하나씩 답합니다.
3. 충분히 정리됐다 싶으면 대화 내용을 intent.md로 정리해 달라고 요청합니다.
4. 프로젝트 최상위 intent/ 폴더에 저장하게 합니다.
5. 저장된 intent.md를 끝까지 읽고 잘못된 부분을 직접 고칩니다.

작성자(originator, 요청을 처음 낸 사람)는 전문가가 아니어도 됩니다. 고객, PM(제품 기획·관리 담당자), 개발자 누구든 가능합니다. 다만 originator 본인이 intent.md를 끝까지 읽고 잘못된 부분을 직접 고쳐야 합니다. intent가 쌓이면 Notion·Linear 같은 업무 관리 도구로 백로그(앞으로 할 일 목록)화해 우선순위 태그를 붙입니다.

2. Spec — 정해진 프롬프트로 자동 생성

spec은 요구사항과 설계를 구체적으로 적은 명세서입니다. intent.md가 확정되면 hook으로 spec 생성을 트리거합니다. hook은 파일 저장 같은 특정 순간이 오면 정해 둔 동작이 자동으로 실행되게 거는 설정이고, 트리거한다는 것은 그 동작을 시작시킨다는 뜻입니다. 영상에서 공개한 프롬프트(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·Test Sprite·Cursor Browser 같은 브라우저 자동 조작 도구로 앱을 직접 실행해 스크린샷·화면 녹화를 남깁니다. skill 변경이나 모델 업그레이드 시에는 약 20개 이슈로 구성된 evaluation 세트(성능을 채점하려고 모아 둔 시험 문제 묶음)를 CI에서 돌려 회귀 여부를 확인합니다. CI는 코드를 올릴 때마다 자동으로 검사를 돌리는 시스템이고, 회귀는 전에 잘 되던 기능이 새 변경 때문에 망가지는 것을 말합니다.

6. Deploy — 사람 리뷰 뒤 에이전트 리뷰가 한 번 더

배포는 만든 결과를 실제 사용자가 쓰는 서비스에 반영하는 일입니다. 사람이 최종 리뷰를 한 뒤, 에이전트가 자기 브랜치(원본을 건드리지 않고 따로 갈라 작업하는 줄기)에서 만든 변경으로 pull request를 만듭니다. pull request는 "이 변경을 원본에 합쳐 달라"고 검토를 요청하는 절차입니다.

Claude가 정책·보안 프로토콜 기준으로 비동기 리뷰를 달면, 별도 Claude Code 인스턴스(따로 실행한 또 하나의 클로드 코드)가 그 코멘트를 다시 확인합니다. 승인·릴리즈 일정 조건이 충족되기 전엔 배포를 막는 hook을 걸 수 있습니다. PR 완료 후엔 bugbot·security review 같은 별도 에이전트가 보안·CI를 한 번 더 점검합니다.

7. Maintain — 진단이 먼저 끝나 있다

장애·신규 티켓(처리할 문제나 요청을 적은 업무 카드)·Slack 메시지·스케줄이 사람 개입 없이 Claude를 트리거합니다. Claude가 로그(프로그램이 남긴 작동 기록)·티켓을 근거로 진단하고 스스로 intent.md를 생성합니다. 페이지 장애나 API rate limit(정해진 시간 안에 보낼 수 있는 요청 횟수 한도) 급증 같은 임계치를 정해두면, 사람이 확인하기 전에 진단·제안이 이미 준비돼 있습니다.

클로드 코드 개발 워크플로를 관통하는 원칙

전체를 관통하는 원칙은 하나입니다. 워크플로를 표준화하고 자주 바꾸지 않습니다. superpowers, BMAD 같은 기존 워크플로(공개된 에이전트 개발 절차 모음)가 있다면 전면 교체할 필요 없이 참고해서 취사선택하면 됩니다. 목표는 SDLC(기획부터 유지보수까지 소프트웨어 개발 전 과정) 전 단계에 에이전트를 넣어 사람 개입 시간을 줄이되, 중요한 검토 지점에는 사람을 남겨두는 데 있습니다.

원문: youtu.be/…