VS Code Copilot을 위한 Spike -> Plan -> Change 구조화된 구현 워크플로

실용적 조언

work/spike/, work/todo/, work/done/과 같은 디렉토리 구조를 사용하여 에이전트의 작업 진행 상황과 산출물을 관리하라.
에이전트에게 티켓을 줄 때 'Out of Scope' 섹션을 명시하여 불필요한 기능 추가를 방지하라.

섹션별 상세

AI 에이전트가 모호한 작업을 받을 때 연구 대신 코드를 먼저 쓰거나 범위를 초과하는 등의 고질적인 문제를 지적했다. 이를 해결하기 위해 각 단계가 하나의 작업과 하나의 산출물만 생성하도록 파이프라인을 엄격히 분리해야 한다. 단계별 분리는 에이전트가 가장 흥미를 느끼지 못하는 연구와 테스트 단계를 건너뛰는 현상을 방지하는 핵심 장치이다.

'/spike' 단계는 코드 구현 없이 오직 연구만 수행하며 코드베이스를 분석하고 2~3가지 접근법을 비교표로 작성한다. 결과물은 'work/spike/[이름].md' 파일에 기록되며 여기에는 위험 요소, 성능 영향, 접근성 등이 포함되어야 한다. 구현 코드를 작성할 수 없도록 강력한 제약을 걸어 에이전트가 연구에만 집중하게 만든다.

'/plan' 단계는 연구 문서를 읽고 구체적인 작업 티켓을 생성하며 수용 기준과 TypeScript 인터페이스 등을 정의한다. 영향받는 파일 목록과 테스트 케이스를 명시하고 '범위 외(Out of Scope)' 섹션을 두어 작업의 경계를 확실히 한다. 이 단계의 에이전트 역시 실제 코드를 구현하는 행위는 엄격히 금지된다.

'/change' 단계는 티켓에 명시된 내용만 정확히 구현하며 테스트 작성과 CI 검증 스크립트 실행을 필수적으로 수행한다. 티켓에 명시되지 않은 파일 수정이나 임의의 리팩터링은 허용되지 않으며 모든 수용 기준이 충족되어야 완료로 간주한다. 이러한 제약은 에이전트가 프로젝트의 의도와 다른 '개선'을 임의로 수행하는 것을 막아준다.

용어 해설

스파이크(Spike): — 소프트웨어 개발에서 해결책을 찾기 위해 수행하는 짧고 집중적인 연구 작업이다. 실제 구현 전에 기술적 불확실성을 제거하고 위험 요소를 파악하는 데 필수적이며, 에이전트가 코딩 전 반드시 거쳐야 할 첫 번째 단계로 정의된다.
수용 기준(Acceptance Criteria): — 사용자 스토리가 완료되었음을 인정받기 위해 충족해야 하는 구체적인 조건들의 목록이다. 에이전트가 구현을 마친 후 결과물이 요구 사항에 부합하는지 검증하는 기준이 되며, 명확한 기준 설정은 에이전트의 작업 범위를 제한하는 효과가 있다.
라이트하우스 오디트(Lighthouse Audit): — 웹 페이지의 품질을 측정하기 위해 구글에서 제공하는 오픈 소스 자동화 도구이다. 성능, 접근성, SEO 등을 평가하며 에이전트가 구현한 코드가 표준을 준수하는지 확인하는 최종 검증 단계에서 사용된다.

언급된 도구

VS Code Copilot추천

AI 기반 코드 보조 및 에이전트 워크플로 실행

Lighthouse추천

구현된 코드의 성능 및 접근성 검증