Anthropic의 'intent.md' 파일로 본 AI 시대 개발 전략

Anthropic에서 제안하는 'intent.md' 파일은 코드를 짜기 전에 해당 코드를 왜 짜야 하는지에 대한 의도를 명확히 정의하는 문서입니다. 이는 단순한 개발 규칙을 넘어서, AI 기반의 소프트웨어 개발 라이프사이클(SDLC)을 시작하는 중요한 출발점 역할을 합니다.

이 파일은 개발 프로세스에서 AI 에이전트의 효율적인 활용을 위한 핵심 도구로, 개발 의도를 기록하여 모든 팀 구성원이 이해할 수 있도록 돕습니다.

현재 'intent.md' 파일은 Claude와 같은 코딩 에이전트가 직접 읽어서 인식할 수 있는 구조는 아닙니다. 따라서, 개발자는 Claude 코드나 다른 코딩 에이전트에게 이 파일을 읽도록 지시하는 별도의 설정(예: Claude.md나 Agent.md 파일에 참조 설정)을 해주어야 합니다.

'intent.md'가 포함하는 5가지 섹션(Problem, Proposed outcome, Affected users and systems, Constraints, Open questions)은 Anthropic이 권장하는 포맷일 뿐, 아직 업계 표준으로 정립된 것은 아니므로 유연하게 적용할 수 있습니다.

기존의 SDLC는 빌드 단계의 효율화에 중점을 두었으나, AI 에이전트를 활용하면서 몇 주에서 몇 달이 걸리던 코드 생성 작업이 이제 몇 시간 단위로 극단적으로 단축되었습니다. 그러나 빌드 단계의 혁신적인 단축에도 불구하고, 계획, 설계, 테스트, 배포, 유지보수와 같은 후속 단계들은 여전히 많은 시간을 소요하며 사람의 개입에 의존하고 있어 전체 개발 프로세스의 병목 현상이 발생하고 있습니다.

이는 코드 리뷰, 승인 등 사람이 직접 수행하는 작업들이 AI의 속도에 맞춰 효율화되지 못하면서 전체 개발 주기의 비효율을 초래하고 있다는 문제 인식을 기반으로 합니다.

결국 에이전트가 빠르게 코드를 생성하더라도, 나머지 과정이 수동으로 진행되면 전체적인 생산성 향상에는 한계가 있음을 시사합니다.

전통적인 개발 방식에서 코드는 의도에 대한 기록이 남지 않아 코드 리뷰 시 개발자가 의도를 해석해야 하는 부담이 있었습니다. AI 네이티브 SDLC는 기존 SDLC와 전체적인 단계는 동일하지만, 각 단계의 흐름과 운영 방식에서 큰 차이를 보입니다.

특히 AI 에이전트가 개발 루프의 모든 지점에 적극적으로 개입하여 작업을 수행함으로써, 코드의 의도부터 설계, 구현, 테스트, 배포에 이르는 전 과정에서 AI의 역할을 극대화하고 있습니다.

과거에는 기획자와 이해관계자 간의 소통을 통해 아이디어를 문서화했지만, AI 네이티브 SDLC에서는 클로드와 같은 AI 에이전트와의 대화를 통해 'intent.md' 문서를 생성하는 시스템을 구축합니다. 이는 아이디어를 낸 고객이나 CS 티켓을 처리하는 담당자 등 누구든지 AI와 소통하여 문서를 만들 수 있음을 의미합니다.

결과적으로 'intent.md'는 사람과 에이전트가 공동으로 참조하는 '단일 진실 원천(Source of Truth)'으로 기능하며, 개발 초기 단계부터 의도를 명확히 하고 공유하는 데 핵심적인 역할을 수행합니다.

AI 에이전트를 사용하는 빌드 단계에서는 코드 작성 자체는 더 이상 병목이 아니며, 이제는 AI가 우리 팀의 규칙을 얼마나 잘 이해하고 있는지가 핵심적인 병목 지점으로 이동했습니다. 이에 따라 팀은 클로드.md와 같은 규칙 파일을 활용하고, 개별 스킬을 정의하여 아키텍처 및 보안 기준을 AI 에이전트가 준수하도록 관리해야 합니다.

이러한 과정을 통해 팀 전체가 공유하는 기술적 규범들이 AI 에이전트의 내부 규칙으로 정착되어, AI가 생성하는 코드의 품질과 일관성을 보장할 수 있게 됩니다. 즉, AI는 단순한 코드 생성 도구를 넘어 팀의 개발 문화와 규범을 내재화한 개발 주체로 기능하게 됩니다.

AI 네이티브 SDLC에서는 단순히 코드만 테스트하는 것이 아니라, 에이전트가 참조하는 시스템 규칙이나 스킬이 변경될 때도 일관성을 보장하기 위한 테스트가 강조됩니다. 이는 CI(지속적 통합) 파이프라인에서 규칙 변경을 트리거로 삼아 20개에서 50개에 달하는 테스트 케이스를 자동으로 실행하는 방식으로 구현될 수 있습니다.

이를 통해 이전 배포된 기능과 동일한 품질의 결과물이 계속해서 나오는지 상시적으로 검증하며, AI 시스템 전체의 안정성과 신뢰성을 유지합니다.

AI 네이티브 SDLC에서는 사람의 컨디션에 따라 발생할 수 있는 코드 리뷰 퀄리티의 편차를 해소하기 위해 에이전트가 다층적인 자동 리뷰를 수행합니다. 이를 통해 사람은 전체 코드를 한 줄 한 줄 검토하는 대신, 결제나 인증과 같이 위험도가 높은 핵심 코드 영역에만 집중하여 리뷰의 효율성을 극대화할 수 있습니다.

에이전트가 기본적인 리뷰를 담당함으로써, 사람은 더 중요한 의사 결정과 보안 문제에 집중할 수 있게 되어 개발 프로세스의 안정성과 속도를 동시에 향상시킬 수 있습니다.

AI 네이티브 SDLC에서는 각 개발 단계에서 생성되는 산출물을 명확히 정의하고 통합 관리합니다. 먼저 플랜 단계에서는 의도를 정의한 'intent.md' 파일이 생성됩니다. 이어서 설계 단계에서는 'intent.md'를 기반으로 구체적인 사양을 정의하는 'spec.md' 파일이 만들어집니다.

그리고 빌드 단계에서는 구현 계획을 담은 'plan.md' 파일이 생성됩니다. 이처럼 모든 개발 단계의 산출물은 하나의 레포지토리에 누적되어 관리되며, 이는 지식의 단일 진실 원천(SSOT)을 구축하는 데 기여합니다.

'intent.md' 파일은 개발 의도를 전달하는 문서이므로, 사실상 개발자가 아닌 그 의도를 가진 누구라도 작성을 시작할 수 있는 구조를 만드는 것이 중요합니다. 이는 기획자, PM, CS 담당자 등 다양한 이해관계자가 참여하여 템플릿 기반으로 AI와 대화하며 의도를 구체화하는 방식으로 이루어집니다.

예를 들어, 배송 상태 변경과 같은 구체적인 문제를 정의하는 것부터 'intent.md' 작성 프로세스가 시작될 수 있습니다.

AI 네이티브 SDLC의 첫 단계에서는 이해관계자가 'intent.md'의 초안을 작성합니다. 이 초안은 이후 PO(Product Owner)의 승인을 받는 시스템을 거치게 됩니다.

PO의 승인이 완료되면, 해당 'intent.md' 파일은 팀의 레포지토리 내 'intent' 폴더 안에 MD 파일 형태로 저장되는 구조로 관리됩니다.

'intent.md' 파일과 'spec.md' 파일은 모두 사람이 아닌 AI 에이전트가 초안을 작성하도록 설계됩니다. 그리고 이 초안에 대한 최종 승인 주체는 PO(Product Owner)가 됩니다. 이는 정책이나 비즈니스 목표를 반영하는 중요한 결정이기 때문입니다.

반면, 'plan.md' 파일은 개발자가 직접 검토하고 완성하는 역할을 맡게 됩니다.

AI를 활용한 개발에 있어서는 모든 지식의 원천을 한곳에 모아두는 SSOT(Single Source of Truth) 구조를 만드는 것이 매우 중요합니다. 이를 위해 Jira나 Confluence와 같은 다양한 도구 대신, 하나의 레포지토리에서 모든 작업과 지식을 통합하여 관리하는 구조가 제안됩니다.

GitHub, Slack, Claude 세 가지 도구만을 활용하여 개발 환경을 단순화하고, 기획자나 CS 담당자와 같은 비개발자도 'intent.md'의 작성 주체가 될 수 있도록 함으로써, 모든 이해관계자가 동일한 정보에 접근하고 기여할 수 있는 환경을 조성합니다.

'intent.md' 초안이 생성되면 GitHub에 PR(Pull Request)을 생성하여 올리고, 팀의 PO(Product Owner)가 이를 검증하고 승인하는 워크플로우를 따릅니다. 이 PR이 승인되고 머지되면 CI(지속적 통합) 잡이 자동으로 동작하여 스펙 문서가 자동 생성됩니다.

생성된 스펙 문서는 다시 승인 절차를 거치고, 최종 승인 시 담당 개발자에게 Slack 멘션 알림이 전송되어 개발 프로세스의 다음 단계로 자연스럽게 연결됩니다.

Anthropic이 제안하는 첫 번째 구조는 모든 개발의 시작점이 '의도(Intent)'라는 관점에서 출발합니다. 따라서 프로젝트의 루트 디렉토리에 'intent' 폴더를 생성하는 것이 기본입니다.

이 'intent' 폴더 안에는 각 기능 또는 문제(슬러그)별로 폴더를 만들고, 그 안에 'intent.md', 'spec.md', 'plan.md' 세 가지 핵심 파일을 구성하여 개발 의도부터 설계, 계획까지 체계적으로 관리합니다.

인텐트를 생성할 때는 별도의 인텐트 브랜치를 통해 GitHub PR(Pull Request)을 생성합니다. 이 PR은 'intent.md' 파일 하나만을 포함하며, 담당자의 검토가 완료되면 PR을 머지하여 인텐트를 공식적으로 승인하는 단계로 간주합니다.

이후 스펙 PR과 플랜 PR이 순차적으로 진행되어, 개발 의도부터 구현 계획까지의 모든 과정이 PR 기반으로 투명하게 관리되고 승인됩니다.

효율적인 의도 관리를 위해 각 폴더당 인텐트, 스펙, 플랜은 각각 하나씩만 생성하는 것이 중요합니다. 만약 하나의 폴더 안에 두 개 이상의 스펙이 필요하다면, 이는 애초에 상위 피처 단위를 더 작게 분리하여 인텐트 자체를 두 개로 나누어 구분해야 할 필요성을 시사합니다.

또한, 기존 레거시 시스템과의 공존이 필요할 경우, AI 네이티브 SDLC를 한 번에 전면 도입하기보다는 점진적이고 단계적인 도입을 권장합니다.

이번 영상에서 강조된 AI 네이티브 SDLC 도입의 핵심 가치는 AI를 사용하면서 의도를 명확하게 전달하는 것의 중요성입니다. 기존 개발 라이프사이클과는 다르게 모든 개발 단계에 AI를 최대한 도입하여 초안을 생성하고, 사람은 꼭 필요한 부분에 대해서만 승인할 수 있는 시스템을 구축하는 것이 중요해지고 있습니다.

이는 코드 리뷰 시 의도를 해석하는 데 드는 비용을 절감하고, 개발 프로세스의 전반적인 효율성을 극대화하는 데 기여합니다.