요구사항 ID를 사용하여 AI 생성 코드를 추적 가능하게 만들기

번호가 매겨진 요구사항은 제품 결정과 이를 구현하는 작업, 테스트 및 코드 간의 연결고리 역할을 할 수 있습니다. 저희의 스펙 기반 워크플로우에서는 1.1이나 1.3 같은 ID가 엔지니어와 AI 에이전트에게 기능 의도부터 실제 구현까지 지속 가능한 경로를 제공합니다.

이러한 연결 고리는 매우 중요합니다. 왜냐하면 AI 코딩 세션은 그 코드를 생성한 추론 과정 없이 코드만 남길 수 있기 때문입니다. 요구사항과 결정 사항이 프롬프트나 에이전트의 임시 계획에만 존재한다면, 미래의 변경 작업은 구현된 내용으로부터 원래의 의도를 재구성해야 합니다.

기능 의도를 리포지토리에 담기

사소하지 않은(non trivial) 기능을 위해서는 구현 전에 명세서(specification)를 작성합니다. 이 문서는 보통 Markdown 형식으로 전용 specs/ 폴더에 저장되며, 예상되는 동작, 관련 상호작용, 엣지 케이스, 기술적 결정 사항, 그리고 결과를 검증하는 방법을 설명합니다.

이 스펙은 팀과 에이전트 모두를 위한 공유된 진실의 원천(shared source of truth)입니다. 이는 작업 후에 추가되는 문서가 아니며, 모든 엔지니어링 관례를 모아두는 장소도 아닙니다. 목표는 작업이 설계되고, 테스트되고, 변경되는 동안 기능 의도를 사용할 수 있도록 만드는 것입니다.

이 접근 방식은 특히 제품 동작에 대한 결정이 명확하지 않은 간략한 지침(brief)의 경우 유용합니다. 예를 들어, 무료 등급 제한(free tier limits)은 사용자가 저장 공간 한도에 도달했을 때, 업로드를 시도할 때, 또는 업그레이드할 때 어떤 일이 발생하는지에 대한 결정이 필요합니다. 이러한 시나리오를 테스트 가능한 요구사항으로 변환하면, 에이전트가 단순히

ID는 테스트가 예상되는 동작과 연결되도록 하는 데도 도움을 줍니다. 이 워크플로우에서 에이전트는 승인된 명세(spec)를 읽고, 먼저 테스트 코드를 작성한 다음, 테스트가 통과할 때까지 구현합니다. 이러한 테스트는 식별된 요구사항에 기반하므로, 단순히 특정 구현이 실행된다는 것을 보여주는 것이 아니라 어떤 동작을 검증하는지 표현할 수 있습니다.

참조(reference)를 간결하게 유지하세요. ID는 설명으로 연결됩니다. 모든 주석이나 테스트 이름에 전체 요구사항을 포함할 필요가 없습니다. 이렇게 하면 코드를 읽기 쉽게 유지하면서도 결정 사항까지 되돌아갈 경로를 보존할 수 있습니다.

구현 전에 승인 결정하기

이 프로세스는 네 가지 단계로 구성됩니다: 요구사항(requirements), 설계(design), 작업(tasks), 그리고 구현(implementation). 다음 단계가 시작되기 전에 사람이 각 단계를 승인합니다.

요구사항은 기능 개요서(feature brief)를 인수 기준(acceptance criteria)으로 변환합니다. 설계는 API 형태, 데이터베이스 설계, 데이터 모델 변경, 제품 동작, 아키텍처 제약 조건 등을 포함하여 기술적 선택을 명시적으로 만듭니다. 작업은 승인된 계획을 구현 단계로 나눕니다. 오직 그 후에야 구현이 시작됩니다.

이 순서는 에이전트가 코드를 변경하기 전에 검토된 컨텍스트를 제공합니다. 또한 사람이 이해 부족을 설계, 작업, 테스트, 구현으로 확산시키기 전에 수정할 수 있는 체크포인트를 만듭니다. 구현 후에는 Gemini나 Cursor Bug Bot과 같은 자동화된 리뷰어가 로컬 테스트 전에 코드를 검토할 수 있습니다.

이 워크플로우는 여전히 진화하고 있습니다. 특히 기능이 커짐에 따라 작업(tasks)은 이탈하거나 정렬을 유지하기 더 어려워질 수 있습니다. 각 작업을 커밋에 매핑하면 명세, 수행된 작업, 코드 기록 간의 연결을 더 깔끔하게 만들 수 있지만, 팀들은 시간이 지나도 작업 구조가 유용하게 유지되는지 주의해야 합니다.

기능 명세를 리포지토리 규칙과 분리하기

기능 명세는 해당 기능의 동작과 결정 사항을 설명해야 합니다. 일반적인 엔지니어링 관례는 리포지토리 지침 파일, 에이전트 규칙 또는 스킬(skills)과 같은 다른 곳에 속합니다. 템플릿은 요구사항, 설계 및 작업 파일을 일관되게 유지할 수 있도록 도와줍니다.

이 경계는 모든 새로운 명세서(spec)가 코딩 선호도를 반복하거나 관련 없는 아키텍처 정책을 포함하는 것을 방지합니다. 또한 에이전트가 올바른 컨텍스트를 찾도록 돕습니다: 명세서의 기능 동작, 저장소 규칙의 영속적인 프로젝트 관례, 그리고 스킬(skills)의 재현 가능한 절차입니다.

더 광범위한 아키텍처 변경 사항 역시 같은 주의를 요합니다. 예를 들어, 알림 기능은 전달 시점, 트리거링 이벤트, 지속성(persistence), 채널에 대한 질문을 제기합니다. 이는 해결해야 할 기능적 결정들입니다. 메시지 큐나 새로운 데이터 저장소를 도입하는 것은 더 광범위한 아키텍처 변화이며, 단일 기능 명세서에 몰래 넣기보다는 저장소 수준의 규칙이나 스킬이 필요할 수 있습니다.

실용적인 시작점은 여러 의미 있는 엣지 케이스(edge case)를 가진 하나의 기능에 대한 명세서를 작성하는 것입니다. 인수 기준(acceptance criteria)에 번호를 매기고, 작업과 테스트에서 이를 참조하며, 구현을 승인된 설계와 연결해 유지합니다. 그런 다음 나중에 합류한 사람이 그 동작을 설명하는 요구사항까지 추적할 수 있는지 검토해야 합니다.

미래의 엔지니어와 에이전트가 구현과 함께 의도(intent)를 필요로 하므로, 명세서는 코드와 함께 배포되어야 합니다.