사양 주도 개발 작업 흐름 완벽 해설

사양 주도 개발 작업 흐름은 요구 사항과 코드 작업을 분리하고, 버전과 작업 번호, 테스트 결과로 다시 연결하는 방식이 가장 안전합니다. 인공지능 코딩 에이전트가 요구에서 전체 코드를 한 번에 만들도록 맡기지 말고, 사양 검토와 기술 계획을 먼저 승인한 뒤 검증 가능한 작은 작업을 순서대로 실행해야 합니다.

이 글은 실제 저장소에 이 방식을 도입하려는 개발팀, 인공지능이 만든 코드를 여러 사람이 검토해야 하는 책임자, 원격 코딩 에이전트에게 긴 작업을 맡기되 진행 상태를 추적하려는 개발자를 위한 내용입니다.

두 개의 작업 줄기를 먼저 분리해야 합니다

사양 주도 개발의 핵심은 문서가 많아지는 데 있지 않습니다. 사양 줄기와 코드 줄기의 책임을 나누는 데 있습니다.

사양 줄기는 다음을 관리합니다.

• 해결하려는 사용자 문제
• 핵심 행동과 결과
• 하지 않을 범위
• 예외와 위험 조건
• 승인 가능한 검수 기준

코드 줄기는 다음을 관리합니다.

• 영향을 받는 파일과 구성 요소
• 의존성 변경
• 자료 이전 방법
• 테스트와 검증 명령
• 실제 코드 차이

두 줄기를 연결하는 식별자는 기능 번호, 사양 항목 번호, 작업 번호, 변경 버전입니다. 이 연결이 없으면 코드가 사양에서 나온 것인지, 에이전트가 범위를 임의로 넓힌 것인지 확인하기 어렵습니다.

공식 사양 도구의 기본 흐름도 사양 작성, 기술 계획, 작업 생성, 구현으로 이어지며, 필요할 때 명확화와 일관성 검사를 추가하도록 구성되어 있습니다. 공식 빠른 시작 문서에서도 각 단계가 다음 단계의 문서를 입력으로 사용하도록 설명합니다.

요구 검토는 모호함을 경계로 바꾸는 단계입니다

요구를 받은 즉시 사양을 쓰면 안 됩니다. 먼저 요구가 판정 가능한지 확인해야 합니다.

예를 들어 “사용자가 더 쉽게 파일을 공유하게 해 달라”는 목표만으로는 구현을 시작할 수 없습니다. 어떤 사용자가 대상인지, 공유 대상이 누구인지, 권한이 없는 사용자는 무엇을 보게 되는지, 실패했을 때 어떤 안내가 나와야 하는지가 빠져 있기 때문입니다.

요구 검토에서 입력과 출력은 다음처럼 정리합니다.

이 단계의 산출물은 긴 문서가 아니라 승인된 요구 목록과 미해결 질문 목록입니다. 결과를 확인할 수 없는 문장은 질문 목록으로 되돌립니다. 질문이 남아 있는데 기술 계획으로 넘어가면 에이전트는 빈칸을 추측으로 채우게 됩니다.

장면 사례: 검색 기능 개선 요청

제품 담당자가 “검색 결과가 더 정확해야 한다”고 요청했다고 가정하겠습니다.

검토 전에는 목표가 모호합니다. 검토 후에는 다음처럼 바뀌어야 합니다.

• 대상: 로그인한 일반 사용자
• 행동: 제목과 설명에 포함된 단어로 자료 검색
• 성공 조건: 검색어와 일치하는 자료가 우선 표시됨
• 제외 범위: 추천 검색어와 외부 자료 검색은 이번 변경에서 제외
• 위험 조건: 권한이 없는 자료는 검색 결과에 노출하지 않음

이렇게 작성하면 사양은 기능 설명이 아니라 검수 기준을 가진 작업 계약이 됩니다.

사양과 기술 계획은 서로 다른 문서여야 합니다

사양은 무엇을 해야 하는지를 설명하고, 기술 계획은 저장소 안에서 어떻게 바꿀지를 설명합니다. 두 문서를 섞으면 기술 선택이 요구 사항처럼 굳어지고, 나중에 구조를 바꾸기 어려워집니다.

사양에는 행동, 자료, 인터페이스 결과, 오류 상황, 승인 조건을 넣습니다. 각 항목에는 변경 요청 번호를 붙입니다. 또한 내용을 다음 세 종류로 구분하면 검토가 쉬워집니다.

• 업무 사실: 제품 정책이나 사용자 약속
• 기술 제약: 현재 저장소 구조, 지원 환경, 보안 규칙
• 확인 필요: 담당자 승인이 아직 없는 부분

기술 계획에서는 저장소 영향 범위를 조사합니다. 어떤 구성 요소가 바뀌는지, 새 의존성이 필요한지, 자료 구조를 이전해야 하는지, 기존 검사가 충분한지를 기록합니다.

공식 문서에서도 사양 단계에서는 무엇을 만들지에 집중하고, 기술 계획 단계에서 기술 구성과 구조를 정하도록 구분합니다. 사양과 계획 단계의 공식 설명을 기준으로 팀 문서 양식을 맞추면 단계 간 책임이 흐려지는 문제를 줄일 수 있습니다.

고위험 변경은 계획을 바로 작업으로 쪼개지 않습니다. 자료 이전, 권한 체계, 외부 인터페이스 변경처럼 실패 비용이 큰 항목은 사람이 먼저 승인해야 합니다.

주의: 사양에 “기술적으로 쉬운 방법”을 미리 적어 두면 에이전트가 그 선택을 사실로 받아들일 수 있습니다. 기술 선택이 확정되지 않았다면 반드시 미확정 항목으로 표시해야 합니다.

기존 저장소에 연결할 때 필요한 준비

새 저장소에서 시작할 때보다 기존 저장소에 도입할 때 확인할 항목이 많습니다. 문서 폴더만 추가해서는 흐름이 작동하지 않습니다.

먼저 다음을 조사합니다.

• 기본 작업 줄기와 병합 규칙
• 검사 명령과 실행에 필요한 환경 변수
• 자료 구조와 이전 스크립트
• 자동 배포 조건
• 코드 소유자와 승인 권한
• 에이전트가 접근해도 되는 비밀 값의 범위

사양 파일은 코드와 같은 버전 관리 영역에 두는 편이 추적에 유리합니다. 기능별 폴더를 만들고 사양, 계획, 작업 목록, 검수 결과를 함께 보관하면 변경 이력을 한 번에 확인할 수 있습니다.

공식 사양 도구는 프로젝트 초기화 과정에서 에이전트 통합 방식과 명령 파일을 준비하며, 설치 뒤에도 통합 구성을 갱신할 수 있습니다. 다만 실제 명령 이름과 폴더 위치는 설치한 버전에 따라 확인해야 합니다. 공식 참조 문서와 업그레이드 안내를 배포 전에 대조해야 합니다.

도입 순서는 다음처럼 진행하면 됩니다.

1. 현재 저장소의 검사 명령을 문서화합니다.
2. 기능별 사양 폴더 위치를 정합니다.
3. 사양과 계획의 승인자를 지정합니다.
4. 작업 목록에 대상 파일과 검증 명령을 필수 항목으로 추가합니다.
5. 에이전트가 읽을 수 있는 문서와 읽으면 안 되는 비밀 자료를 구분합니다.
6. 작은 기능 하나를 골라 전체 흐름을 시험합니다.
7. 실패한 단계와 누락된 산출물을 팀 규칙에 반영합니다.

이때 기존 브랜치 전략을 모두 바꿀 필요는 없습니다. 중요한 것은 작업 줄기와 변경 기록 안에 관련 사양과 검증 결과가 함께 남는 것입니다.

인공지능 코딩 에이전트 실행은 작업 단위로 통제합니다

에이전트 작업의 크기는 파일 개수로 정하지 않습니다. 하나의 사양 항목을 구현하고, 하나의 검증 묶음으로 결과를 확인할 수 있는가가 기준입니다.

좋은 작업에는 다음 정보가 포함됩니다.

• 연결된 사양 항목
• 변경 대상 파일
• 변경하지 않을 파일
• 실행할 검사 명령
• 성공 조건
• 실패 시 중단 조건
• 작업 완료 뒤 남길 요약

반대로 “전체 로그인 기능을 구현하고 테스트까지 끝내라”처럼 범위가 넓은 지시는 실패 원인을 찾기 어렵습니다. 화면, 권한, 자료 구조, 검사 작업을 각각 독립된 결과로 나누고 중간 산출물을 저장해야 합니다.

공식 작업 흐름도 작업 목록을 의존 순서에 따라 만들고, 구현 단계에서 그 목록을 순서대로 수행하도록 설명합니다. 큰 기능은 한 번에 실행하지 않고 단계별로 범위를 제한할 수 있습니다. 공식 작업 생성과 구현 안내가 이 구조를 명시합니다.

결정 조건은 다음처럼 적용하면 됩니다.

• 사양 항목 하나와 검증 명령 하나로 결과를 확인할 수 있으면 에이전트에게 맡깁니다.
• 여러 자료 계층을 동시에 바꾸지만 중간 상태를 실행할 수 있으면 단계별 작업으로 나눕니다.
• 실패 시 자료 손실이나 권한 노출이 발생할 수 있으면 사람이 계획을 승인한 뒤 실행합니다.
• 실행 시간이 길고 중단 지점이 불명확하면 검수 지점을 먼저 추가합니다.
• 에이전트가 목표 파일이나 종료 조건을 스스로 정해야 한다면 작업을 더 작게 줄입니다.

장시간 원격 실행에서는 작업 로그만큼 복구 지점이 중요합니다. 각 단계가 끝날 때 사양 경로, 변경 요약, 실행한 검사, 남은 질문을 저장해야 합니다. 공식 작업 흐름 기능은 실행 상태와 로그를 저장하고 중단된 지점에서 다시 이어가는 구조를 지원합니다. 공식 작업 흐름 참조를 적용할 때도 실제 환경에서 로그 보존과 복구 가능 여부를 먼저 시험해야 합니다.

코드 검토는 구현과 사양을 함께 봐야 합니다

코드 검토자는 문법과 성능만 확인하면 안 됩니다. 다음 네 가지를 함께 대조해야 합니다.

• 사양 항목이 모두 구현되었는가
• 예외와 권한 조건이 빠지지 않았는가
• 계획에 없던 파일이나 기능이 추가되지 않았는가
• 테스트 결과가 사양의 승인 조건을 실제로 검증하는가

에이전트가 제출하는 결과에는 차이 요약, 변경 파일, 실행한 검사, 실패한 검사, 미해결 항목을 포함해야 합니다. 검토자는 변경된 코드만 읽지 말고 관련 사양 항목으로 이동해 양쪽의 범위를 대조해야 합니다.

변경 요청을 작게 유지하면 검토자가 목적과 위험을 빠르게 파악할 수 있습니다. 공식 검토 안내도 변경 파일과 차이를 확인하고, 줄 단위 의견과 승인 또는 수정 요청을 남기는 흐름을 설명합니다. 공식 코드 검토 안내를 팀 규칙에 반영하면 검토 결과의 형식을 통일할 수 있습니다.

검토자가 “이 기능도 같이 넣자”고 제안했지만 현재 사양에 없다면 즉시 코드에 추가하지 않습니다. 먼저 사양에 새 요구로 기록하고, 승인 뒤 별도 작업을 생성해야 합니다. 그래야 변경 범위가 코드 검토 중에 조용히 커지지 않습니다.

지속 배포에서는 사양도 함께 갱신해야 합니다

코드가 병합된 뒤 사양을 방치하면 다음 변경부터 다시 구두 설명에 의존하게 됩니다. 병합 전에 사양, 계획, 작업 목록, 테스트, 코드 버전이 서로 맞는지 확인해야 합니다.

배포 뒤 결함이 발견되면 수정 코드부터 만들지 말고 다음 순서로 처리합니다.

1. 결함이 기존 사양의 누락인지 확인합니다.
2. 기존 사양을 고칠지 새 요구로 분리할지 결정합니다.
3. 재현 조건과 검수 기준을 사양에 기록합니다.
4. 승인된 기술 계획과 작업을 생성합니다.
5. 수정 코드와 회귀 검사를 함께 검토합니다.

큰 제품은 전체 기능을 하나의 거대한 문서로 관리하기보다 독립적으로 검증할 수 있는 작은 사양으로 나누는 편이 좋습니다. 공식 문서도 큰 요구를 여러 기능 단위로 나누고, 각 단위에 별도의 사양과 계획, 작업 목록을 두는 방식을 설명합니다. 기능 분할에 관한 공식 문서를 참고할 수 있습니다.

따라서 이 방식은 문서 작성법이 아니라 협업 기록을 운영하는 방법에 가깝습니다. 사양이 바뀌면 작업이 바뀌고, 작업이 바뀌면 코드와 검사가 바뀌어야 합니다.

적용 전 최종 판단 기준

다음 조건을 만족하면 사양 주도 개발을 기존 저장소에 도입할 가치가 높습니다.

• 요구 사항을 제품 담당자와 개발자가 함께 승인할 수 있습니다.
• 사양과 코드 변경을 같은 버전 관리 흐름에서 보관할 수 있습니다.
• 에이전트가 실행할 검사 명령을 자동화할 수 있습니다.
• 고위험 변경을 사람이 승인하는 규칙을 만들 수 있습니다.
• 원격 환경에서 작업 로그와 복구 지점을 보존할 수 있습니다.

반대로 요구가 자주 바뀌고 승인자가 없거나, 검증 명령이 전혀 없는 저장소라면 먼저 사양 도입보다 검토 규칙과 기본 검사부터 정비해야 합니다. 문서만 추가하면 에이전트의 추측이 줄어드는 것이 아니라 관리 비용만 늘어날 수 있습니다.

원격 코딩 에이전트를 실제로 운영할 계획이라면 저장소 격리, 로그 보존, 중단 뒤 복구, 검토자의 안전한 접속을 별도로 확인해야 합니다. kvmboot 도움말 센터에서 원격 환경 운영 조건을 확인하고, 팀 저장소에 맞는 접근 방식이 필요한 경우 kvmboot 문의 창구를 통해 검토할 수 있습니다.

현재 노트북이나 공유 개발 서버에서 장시간 에이전트를 실행하면 전원 관리, 접속 중단, 작업 공간 충돌, 로그 보존 부족이 문제가 되기 쉽습니다. 특히 여러 개발자가 같은 환경을 번갈아 사용하면 사양 파일과 코드 차이의 기준점이 흔들립니다. 단기간에 독립된 원격 실행 환경이 필요하고, 저장소 격리와 검토자 접속 조건을 확인할 수 있다면 kvmboot의 맥 환경을 임시 개발 공간으로 비교해 볼 만합니다. 다만 물리 장치 연결이나 장기 고정 부하가 핵심인 팀이라면 자체 장비가 더 적합할 수 있습니다.