사양 주도 개발 완벽 가이드: AI 코딩 에이전트

같은 기능을 여러 번 고치고도 검수 기준이 계속 달라진다면, AI 코딩 에이전트에 프롬프트를 더 길게 입력할 때가 아닙니다.

가장 빠른 해결책은 요구사항을 제약 조건, 판정 가능한 사양, 독립 작업, 검증 증거로 나누고 각 결과물을 버전 관리하는 것입니다. 이것이 사양 주도 개발의 핵심이며, 에이전트가 코드를 수정하기 전에 지켜야 할 경계를 먼저 고정하는 방식입니다.

이 글은 다음 독자에게 맞습니다.

• AI 코딩 에이전트를 자주 다시 지시해야 하는 개인 개발자
• 팀 개발 과정에 인공지능 코딩을 도입하려는 기술 책임자
• 에이전트가 만든 코드에 감사와 검수 근거가 필요한 개발팀

전체 흐름과 핵심 산출물

사양 주도 개발은 “프롬프트를 잘 쓰는 방법”이 아닙니다. 사용자의 의도를 바로 코드로 전달하지 않고, 다음처럼 단계별 산출물로 변환하는 개발 방식입니다.

프로젝트 규칙을 정하고, 기능의 사양을 작성한 뒤, 설계와 작업 목록을 만들고, 작업 단위로 구현합니다. 마지막에는 테스트와 검수 결과를 원래 사양에 다시 연결합니다.

공식 사양 도구의 기본 흐름도 사양 작성, 기술 계획, 작업 분해, 구현의 순서로 구성됩니다. 도구에 따라 명령 이름과 파일 위치는 달라질 수 있지만, 중간 산출물을 남기고 다음 단계로 넘어간다는 구조는 같습니다. 공식 저장소의 기본 작업 흐름에서 단계별 명령과 산출물 예시를 확인할 수 있습니다.

이 구조가 필요한 이유는 세 가지입니다.

첫째, 에이전트는 현재 대화에 포함된 정보만으로 프로젝트 전체의 불변 규칙을 안정적으로 유지하기 어렵습니다. 둘째, 큰 작업을 한 번에 맡기면 서로 다른 모듈의 변경이 섞여 원인 추적이 어려워집니다. 셋째, “완성됐다”는 말만으로는 요구사항이 충족됐는지 판단할 수 없습니다.

따라서 각 단계에는 다음 네 가지가 있어야 합니다.

• 입력으로 사용하는 문서
• 에이전트가 만들어야 하는 산출물
• 사람이 확인할 검토 지점
• 다음 단계로 넘어가는 종료 조건

프로젝트 제약 조건

사양 주도 개발은 어떻게 시작해야 하는가

시작점은 기능 설명이 아니라 프로젝트의 경계입니다. 저장소에 다음 내용을 고정해 두면 매 작업마다 같은 설명을 반복할 필요가 줄어듭니다.

• 사용 언어와 주요 기술 구성
• 디렉터리별 책임과 파일 배치 규칙
• 실행, 테스트, 정적 검사 명령
• 데이터와 비밀 정보의 처리 원칙
• 변경하면 안 되는 디렉터리와 자동 생성 파일
• 오류 처리와 로그 작성 규칙
• 완료 정의와 병합 조건

이 문서는 저장소의 지침 파일이나 별도의 프로젝트 헌장으로 관리할 수 있습니다. 특정 도구를 사용할 때는 해당 도구가 읽는 파일명과 적용 범위를 공식 문서에서 확인해야 합니다. 예를 들어 일부 개발 환경은 저장소의 지침 파일을 항상 적용하고, 파일 경로별 지침을 별도로 적용합니다. 공식 개발 환경의 사용자 지정 지침 안내는 항상 적용되는 지침과 경로별 지침의 차이를 설명합니다.

주의: 제약 조건을 지나치게 길게 쓰면 에이전트가 중요한 규칙과 참고 정보를 구분하지 못할 수 있습니다. 모든 규칙을 한 문서에 넣기보다 항상 적용할 규칙, 특정 모듈에만 적용할 규칙, 작업별 참고 자료를 분리하는 편이 안전합니다.

프로젝트 제약 조건의 종료 조건은 “문서가 존재한다”가 아닙니다. 새 작업을 받은 에이전트가 저장소를 넓게 탐색하지 않고도 수정 가능 범위, 실행 명령, 금지 사항을 설명할 수 있어야 합니다.

판정 가능한 사양서

소프트웨어 사양은 어느 정도로 작성해야 하는가

사양은 구현 방법보다 동작 결과를 설명해야 합니다. “로그인 기능을 추가한다”는 표현만으로는 실행 가능한 Specification이 되지 않습니다. 다음 항목을 포함해야 합니다.

• 사용자가 하려는 일
• 입력 조건
• 정상적인 결과
• 실패와 예외 상황
• 권한과 보안 조건
• 데이터가 변하는 규칙
• 화면 또는 인터페이스의 관찰 가능한 결과
• 테스트나 수동 검수로 확인할 수 있는 기준

예를 들어 “사용자가 만료된 초대 링크를 열면 오류를 보여준다”는 사양은 다음처럼 구체화할 수 있습니다.

• 만료 시각이 현재 시각보다 이전이면 초대 수락을 허용하지 않습니다.
• 서버는 성공 응답과 다른 오류 상태를 반환합니다.
• 화면에는 다시 초대를 요청할 수 있는 안내를 표시합니다.
• 유효한 링크를 사용한 경우에는 가입 절차가 정상적으로 진행됩니다.

이렇게 작성하면 사양은 단순한 설명이 아니라 검증 기준이 됩니다. 반대로 “빠르게 처리한다”, “사용하기 편해야 한다”, “안전해야 한다”처럼 측정 또는 관찰 방법이 없는 문장은 그대로 두지 않는 것이 좋습니다. 수치가 필요하다면 실제 제품 요구사항이나 검증 가능한 기준에서 가져와야 하며, 근거 없는 성능 숫자를 예시 사양에 넣어서는 안 됩니다.

사양서의 각 항목에는 식별자를 붙이는 편이 좋습니다. 예를 들어 요구사항 1, 요구사항 2처럼 관리하면 작업 목록과 테스트 결과를 연결하기 쉽습니다. 공식 작업 흐름에서도 사양, 계획, 작업을 별도 산출물로 다루며, 각 단계 사이에서 내용을 검토하도록 구성할 수 있습니다. 공식 작업 흐름과 검토 지점 문서를 참고하면 단계 사이에 승인 지점을 배치하는 방법을 확인할 수 있습니다.

사양의 좋은 종료 조건

다음 질문에 모두 답할 수 있으면 에이전트가 실행할 수 있는 수준에 가까워집니다.

• 어떤 입력이 들어오는가
• 어떤 결과가 성공인가
• 어떤 경우에 실패하는가
• 실패 시 사용자와 시스템이 각각 무엇을 보는가
• 어떤 파일이나 인터페이스가 영향을 받는가
• 테스트, 명령, 화면 확인 중 무엇으로 완료를 판단하는가

여기서 중요한 점은 모든 구현 세부사항을 사양서에 적는 것이 아닙니다. 사양은 “무엇을 보장할 것인가”를 결정하고, 설계 계획은 “어떻게 구현할 것인가”를 결정합니다.

설계와 작업 분해

AI 코딩 에이전트는 사양에 따라 어떻게 작업을 나누는가

사양이 작성되면 곧바로 코드 생성으로 넘어가지 말고 먼저 설계 계획을 요청해야 합니다. 설계 계획에는 기술 구성, 영향을 받는 모듈, 데이터 흐름, 외부 의존성, 위험 요소가 포함되어야 합니다.

에이전트에 다음 순서로 요청하면 결과를 검토하기 쉽습니다.

1. 사양에서 구현 대상과 제외 대상을 구분합니다.
2. 영향을 받는 파일과 모듈을 추정하고 근거를 적습니다.
3. 기존 인터페이스와 충돌 가능성을 찾습니다.
4. 구현 선택지를 비교합니다.
5. 선택한 설계와 선택하지 않은 대안을 기록합니다.
6. 독립적으로 구현하고 검증할 수 있는 작업으로 나눕니다.

작업 하나가 너무 크면 에이전트가 여러 모듈을 동시에 수정합니다. 반대로 지나치게 작으면 작업 사이의 의존성을 관리하는 비용이 커집니다. 좋은 작업은 한 문장으로 변경 범위를 설명할 수 있고, 완료 후 별도의 명령이나 검수 절차로 결과를 확인할 수 있어야 합니다.

공식 도구의 작업 생성 단계는 구현 계획에서 실행 가능한 작업 목록을 만들도록 설계되어 있습니다. 구현 단계 역시 선행 조건과 작업 순서를 확인한 뒤 진행하도록 안내합니다. 공식 핵심 명령 참고 문서에는 프로젝트 초기화와 작업 단계의 역할이 정리되어 있습니다.

작업 목록에는 다음 내용을 함께 적는 것이 좋습니다.

• 작업 식별자
• 변경 대상
• 선행 작업
• 수정하지 않을 범위
• 실행할 검증 명령
• 완료 시 생성해야 하는 증거

예를 들어 “회원 기능 구현”은 너무 큽니다. “초대 토큰 검증 함수 추가”, “만료 토큰 오류 응답 테스트 추가”, “가입 화면에 재요청 링크 표시”처럼 나누면 각 작업의 실패 원인을 좁힐 수 있습니다.

작업 단위 구현

구현 단계에서는 현재 작업에 필요한 사양과 관련 코드만 에이전트에 제공합니다. 저장소 전체를 매번 다시 읽게 하는 방식은 불필요한 변경과 문맥 표류를 늘릴 수 있습니다.

각 작업은 다음 순서로 운영하는 편이 안정적입니다.

• 작업을 시작하기 전에 수정 계획을 설명하게 합니다.
• 변경할 파일과 변경하지 않을 파일을 구분하게 합니다.
• 먼저 테스트 또는 검증 기준을 확인하게 합니다.
• 작업을 한 번에 하나의 논리적 변경으로 제한합니다.
• 수정 후 차이점과 실행한 명령을 보고하게 합니다.
• 실패한 검증은 임시 우회가 아니라 원인과 연결해 수정합니다.

에이전트가 계획을 설명했다고 해서 그 내용이 자동으로 승인된 것은 아닙니다. 계획에 사양에 없는 동작이 추가되었거나, 금지된 영역을 수정하려 한다면 구현 전에 중단해야 합니다.

경험상 가장 위험한 문장은 “관련된 부분을 모두 정리해 달라”입니다. 범위가 넓고 종료 조건이 없기 때문입니다. 대신 “이 작업에서는 검증 함수와 해당 테스트만 수정하고, 데이터 구조와 화면 구성은 변경하지 않는다”처럼 경계를 적어야 합니다.

코드가 완성된 뒤에는 결과만 받지 말고 다음 자료를 함께 남겨야 합니다.

• 변경 파일 목록
• 핵심 변경 내용
• 실행한 테스트와 결과
• 아직 확인하지 못한 항목
• 사양과 다르게 결정한 부분

이 자료가 있어야 팀원이 에이전트의 결과를 재현하고 검토할 수 있습니다.

검증과 회귀 처리

검증은 구현의 마지막 부속 절차가 아니라 사양을 실행하는 단계입니다. 각 사양 항목을 테스트, 정적 검사, 인터페이스 예시, 수동 확인 중 하나와 연결해야 합니다.

공식 문서에는 사양과 계획, 작업 사이의 일관성을 분석하는 단계와 구현 후 수렴 여부를 확인하는 흐름도 제시되어 있습니다. 문제가 발견되면 임시 지시를 계속 추가하기보다 문제가 발생한 문서 단계로 돌아가야 합니다. 요구사항 문제는 사양 단계에서, 설계 문제는 계획 단계에서, 작업 범위 문제는 작업 목록 단계에서 고치는 방식입니다. 공식 에이전트 중심 사양 개발 문서에서 이 회귀 원칙을 확인할 수 있습니다.

검수 기록은 다음 표처럼 연결할 수 있습니다.

사양 항목	구현 작업	검증 방법	실패 시 되돌아갈 단계
정상 입력 처리	입력 검증 함수 추가	단위 테스트	작업
잘못된 입력 차단	오류 응답과 화면 처리	인터페이스 테스트	사양 또는 작업
권한 없는 접근 차단	권한 검사 추가	수동 검수와 자동 테스트	설계
기존 기능 유지	회귀 테스트 실행	전체 테스트	계획 또는 구현
운영 로그 기록	로그 형식과 수준 정의	로그 확인	프로젝트 제약 조건

이 표에서 중요한 부분은 실패 시 돌아갈 위치입니다. 테스트가 실패할 때마다 새로운 임시 프롬프트를 덧붙이면 코드에는 예외적인 보정만 쌓입니다. 실패가 요구사항의 모호함에서 시작됐다면 사양을 고치고, 모듈 간 충돌에서 시작됐다면 설계를 다시 검토해야 합니다.

변경 관리와 버전 유지

사양이 바뀌면 코드부터 수정하지 않아야 합니다. 먼저 변경된 의도와 영향 범위를 기록하고, 기존 사양과의 차이를 확인한 뒤 계획과 작업 목록을 갱신해야 합니다.

변경 절차는 다음과 같이 운영할 수 있습니다.

• 변경 요청을 원래 사양의 식별자와 연결합니다.
• 삭제, 수정, 추가된 조건을 구분합니다.
• 영향을 받는 설계와 인터페이스를 찾습니다.
• 기존 테스트가 어떤 조건을 보호하는지 확인합니다.
• 작업 목록을 다시 생성하거나 수정합니다.
• 구현 후 변경된 사양만이 아니라 관련 회귀 항목도 검증합니다.

공식 안내에서도 기존 프로젝트의 기능이 크게 바뀌면 새로운 기능 사양을 만들고, 이전 계획과 작업에서 여전히 유효한 결정을 명시적으로 이어가도록 권장합니다. 기존 프로젝트의 사양 변경 안내를 참고할 수 있습니다.

큰 기능을 한 번에 구현하기 어렵다면 전체 기능을 작은 독립 사양으로 나누는 방법도 있습니다. 각 하위 기능이 자체 사양, 계획, 작업 목록을 가지면 에이전트가 전체 목표를 잃지 않으면서도 작은 단위로 검증할 수 있습니다. 독립 사양으로 기능을 나누는 공식 설명에 이 방식의 기준이 제시되어 있습니다.

구현 전 점검 목록

아래 항목은 개인 프로젝트와 팀 저장소에서 모두 사용할 수 있습니다.

• [ ] 프로젝트의 기술 구성과 실행 명령을 문서화했습니다.
• [ ] 수정 금지 영역과 보안 경계를 적었습니다.
• [ ] 기능 요구사항을 입력, 결과, 예외로 나눴습니다.
• [ ] 각 사양 항목에 검증 방법을 연결했습니다.
• [ ] 설계 계획에서 영향을 받는 모듈을 확인했습니다.
• [ ] 작업을 독립 구현 단위로 나눴습니다.
• [ ] 각 작업의 선행 조건과 종료 조건을 적었습니다.
• [ ] 에이전트가 수정 전에 계획을 보고하도록 했습니다.
• [ ] 수정 후 차이점과 실행 결과를 기록하도록 했습니다.
• [ ] 실패한 검증이 어느 단계의 문제인지 판단했습니다.
• [ ] 변경된 사양과 코드, 테스트를 같은 버전 흐름에 반영했습니다.

사양 주도 개발의 장점은 에이전트가 항상 정확한 코드를 만든다는 데 있지 않습니다. 오히려 잘못된 결과가 나왔을 때 어느 문서와 어느 작업으로 돌아가야 하는지가 분명해진다는 데 있습니다.

현재 방식이 긴 채팅 기록과 개인별 로컬 환경에 의존한다면, 요구사항이 바뀔 때마다 문맥이 사라지고 테스트 환경도 달라지며 팀원이 같은 결과를 재현하기 어렵습니다. 특히 장기간 실행되는 작업이나 여러 운영 체제에서 확인해야 하는 프로젝트에서는 로컬 환경의 차이와 초기화 비용이 반복적인 장애 원인이 됩니다.

이런 경우에는 사양 문서와 버전 관리뿐 아니라, AI 코딩 에이전트가 매번 같은 조건에서 실행할 수 있는 재설정 가능한 개발 환경도 함께 준비해야 합니다. 단기간의 기능 검증이나 원격 테스트가 목적이라면 클라우드 맥과 원격 개발 환경 안내를 먼저 확인하고, 실제 맥 환경에서 자동화 테스트가 필요하다면 맥 미니 렌탈 환경과 현재 저장소의 테스트 요구사항을 비교하는 편이 합리적입니다.

다만 장기간 고정 부하를 처리하거나 특정 물리 장치에 직접 연결해야 한다면 렌탈보다 자체 장비가 적합할 수 있습니다. 반대로 짧은 기간 동안 여러 사양을 검증하고, 실패한 작업을 깨끗한 환경에서 다시 실행해야 한다면 Zutcloud의 맥 환경이 로컬 장비를 계속 유지하는 방식보다 운영 부담이 낮을 수 있습니다. 중요한 것은 먼저 사양과 검증 절차를 고정한 뒤, 그 절차를 안정적으로 실행할 환경을 선택하는 것입니다.

더 읽기

• 에이전트 작업 공간을 안전하게 설계하는 방법
• 여러 에이전트의 병렬 개발과 변경 검증을 운영하는 법