스펙 주도 개발 실전: GitHub Spec Kit과 Kiro로 요구사항부터 맞추기

문서를 더 많이 쓰자는 이야기는 아닙니다. 창업자는 잘못된 동작을 걸러내고, 엔지니어는 제안된 설계에 이의를 제기하며, 리뷰어는 머지에 필요한 검증 근거를 확인할 수 있는 짧은 합의 문서가 필요합니다.

처음 시도한다면 지금 사용하는 저장소에서 범위가 명확한 기능을 고르는 것이 좋습니다. 에이전트에게 애플리케이션 전체의 명세를 맡기기보다 내보내기, 승인 규칙, 알림 설정 같은 기능으로 시작하면 이 방식의 효용을 더 분명히 알 수 있습니다.

스펙 주도 개발이란 무엇인가요?

AI 에이전트를 활용하는 스펙 주도 개발은 원하는 동작을 검토해 확정한 명세를 바탕으로 설계, 작업 분할, 구현, 검증을 진행하는 방식입니다. 스펙 기반 개발, 또는 명세 기반 개발이라고도 하는 이 방식에서 스펙은 무엇이 왜 일어나야 하는지를, 설계는 기존 애플리케이션에서 이를 어떻게 구현할지를 설명합니다. 작업 목록은 그 설계를 확인 가능한 단위로 나눕니다.

AI 이전에도 동작 주도 개발(BDD)처럼 명세를 실행 가능한 테스트로 사용하는 관련 개발 방식이 있었습니다. 이 전통은 여기서 설명하는 흐름과 함께 사용할 수 있지만, Markdown 스펙 자체가 실행 가능한 테스트는 아닙니다. Cucumber의 BDD 문서.

실무에서 달라진 점은 코딩 에이전트가 구현하는 내내 이 문서들을 참조할 수 있다는 것입니다. 에이전트의 작업을 체계화하는 오픈 소스 툴킷인 GitHub Spec Kit은 기존 에이전트에 개발 절차를 더합니다. AWS의 코딩 환경인 Kiro는 제품 안에 스펙 워크플로를 갖추고 있습니다. 어느 쪽을 쓰더라도 고객이 어떤 경험을 해야 하는지는 직접 결정해야 합니다.

문서 확인일: 2026년 10월 13일. 아래의 명령어 이름, 파일 경로, 지원 기능은 확인 당시 GitHub, Kiro, Anthropic, OpenAI 문서를 기준으로 합니다. 기능 구현 예시는 설명을 위한 사례이며, 실제 운영 환경에 배포했거나 생산성 향상을 측정했다는 주장은 아닙니다.

개발자에게는 구현 범위를 좁혀 준다는 의미가 있습니다. 에이전트는 기능 주변의 애플리케이션을 다시 설계하지 않고 기존 구조를 재사용해야 합니다. 운영자와 창업자에게는 중요한 판단을 더 일찍 내릴 수 있다는 이점이 있습니다. 내보내기 버튼을 검토하기 전에 누가 데이터를 내보낼 수 있는지부터 정하는 것입니다. 도입을 검토하는 팀이라면 모든 개발자를 새 에디터로 옮길 필요가 없습니다. 지금 쓰는 에이전트로 시작하고, 문서를 계속 관리하는 일이 부담이 될 때 추가 도구에 투자하면 됩니다.

스펙 주도 개발은 어떤 순서로 진행하나요?

각 문서가 답하는 질문이 다르므로 분리해서 관리합니다. 아키텍처 다이어그램으로 빠진 제품 규칙을 결정할 수는 없고, 작업 목록만으로 기능이 제대로 동작한다고 입증할 수도 없습니다.

동작에 대한 결정은 창업자나 제품 책임자가 맡습니다. 설계가 시스템에 맞는지는 엔지니어링 리드가 책임집니다. 에이전트는 둘 다 초안을 작성할 수 있지만, 문장이 매끄럽다고 결정까지 옳다는 뜻은 아닙니다.

스펙 주도 개발 도구, 어느 정도의 체계가 필요할까요?

협업이 어디서 막히는지에 따라 도구를 고릅니다. GitHub Spec Kit은 기존 에이전트를 중심으로 저장소 안에 반복 가능한 절차를 만들고 싶을 때 적합합니다. Kiro는 코딩 환경 안에서 요구사항, 설계, 작업 실행을 함께 관리하려는 개발자에게 맞습니다. 첫 기능을 시도하거나 이미 검토 습관이 잘 잡힌 팀이라면 일반 파일로도 시작할 수 있습니다.

GitHub Spec Kit의 명령어와 검토할 파일

GitHub Spec Kit은 재사용 가능한 지침, 템플릿, 보조 스크립트를 제공합니다. 실제 작업은 선택한 코딩 에이전트가 수행합니다. 현재 README에 명시된 핵심 순서는 프로젝트 원칙 수립, 기능 명세, 설계, 작업 분할, 구현, 남은 누락 사항 확인입니다.

현재 README에 따르면 Python 3.11 이상, Python 패키지 설치 도구인 uv, 지원되는 에이전트가 필요합니다. 설치 예시는 GitHub의 코딩 어시스턴트인 GitHub Copilot을 사용합니다. 터미널에서 다음 명령을 실행합니다.

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

그 디렉터리에서 코딩 에이전트를 실행합니다. 워크플로 지시는 에이전트의 채팅에서 하나씩 실행하고, 결과를 검토한 다음 다음 단계로 넘어갑니다. 아래 지시는 셸 명령어가 아닙니다.

명령어 표기의 차이를 구분해야 합니다. README는 Copilot의 기본 스킬 문법인 /speckit-specify를 사용합니다. 상세 명령어 레퍼런스는 점으로 구분하는 형식인 /speckit.specify를 사용합니다. Codex의 스킬 연동에서는 $speckit-specify를 씁니다. 설치한 연동 방식에 맞는 문법을 사용해야 하며, 구분 기호를 서로 바꿔 쓸 수는 없습니다. 연동 레퍼런스.

명칭과 역할은 GitHub의 Agentic SDD 레퍼런스를 따릅니다. Clarify, checklist, analyze는 품질을 추가로 확인하는 단계입니다. constitution은 지속적으로 적용할 프로젝트 규칙을 정하는 문서이므로, 작은 기능을 추가할 때마다 다시 쓰지 않습니다.

내보내기 예시라면 specify 단계에서 누가 내보낼 수 있는지, 어떤 레코드를 포함하는지, 파일 내용과 실패 시 동작은 무엇인지를 설명합니다. plan 단계에는 기존 기술 스택과 저장소의 제약을 전달합니다. 인수 테스트도 명시적으로 요청해야 합니다. tasks 명령어 문서는 요청이 있을 때 테스트를 생성한다고 안내하므로, 작업 목록이 생성됐다는 사실만으로 적절한 테스트까지 포함됐다고 볼 수는 없습니다.

검토할 파일은 다음과 같습니다.

• .specify/memory/constitution.md: 프로젝트 원칙입니다. Constitution 템플릿.
• specs/<feature-directory>/spec.md: 기능의 동작을 정의합니다. 기능 디렉터리는 보통 specs/ 아래에 있으며, 디렉터리 이름은 생성되거나 설정됩니다. Specify 템플릿.
• 해당 기능 디렉터리의 plan.md와 tasks.md: 구현 설계와 작업 목록입니다. 설계 단계에서는 research.md, data-model.md, quickstart.md도 생성하며, 해당되는 외부 인터페이스가 있으면 contracts/도 만듭니다. Plan 템플릿, 작업 레퍼런스.

구현 후 converge는 코드베이스를 스펙, 설계, 작업 목록과 비교합니다. 누락을 발견하면 tasks.md에 작업을 추가하지만, 코드를 직접 수정하지는 않습니다. 추가된 작업을 구현한 뒤 다시 확인합니다. “Converged” 결과는 검토에 유용한 자료일 뿐, 테스트나 승인을 대신하지 않습니다.

기존 애플리케이션에 적용하는 경우 GitHub의 도입 가이드는 기존 상태를 보존한 뒤 현재 위치에서 초기화하는 방식으로 시작합니다. 명령어는 specify init --here --force --integration <key>이며, <key>를 claude나 codex처럼 문서에 나오는 연동 키로 바꿉니다. 가이드는 --force가 충돌하는 관리 대상 파일을 덮어쓸 수 있다고 경고합니다. 실행 후 diff를 검토해야 합니다. 다음 변경의 명세를 작성하기 전에 애플리케이션 전체의 스펙을 복원할 필요는 없습니다.

한계: Spec Kit은 문서 간 모순을 드러낼 수 있지만, 일관되게 잘못 작성된 비즈니스 규칙은 그대로 받아들일 수 있습니다. 여러 사람이나 여러 세션에서 같은 합의를 공유해야 할 때 추가 파일의 유지 관리 비용을 감수할 가치가 생깁니다.

Kiro로 스펙 주도 개발하기: Specs, Steering, Hooks

Kiro는 기능의 의도, 지속적으로 적용할 프로젝트 지침, 자동 실행 작업을 구분합니다. 이번 기능에는 specs, 저장소 전반의 규칙에는 steering, 반복해서 실행할 점검에는 hooks를 사용합니다.

Kiro의 코드 에디터인 IDE에서 Specs 아래의 **+**를 누르거나 채팅에서 Spec을 선택합니다. Feature를 고른 다음 Requirements-First를 선택합니다. 기술 설계와 작업 분할을 승인하기 전에 요구사항부터 검토합니다. 생성된 기능 디렉터리에는 .kiro/specs/<feature-name>/requirements.md, design.md, tasks.md가 들어갑니다. 작업을 검토한 뒤 작업 인터페이스에서 실행합니다. Kiro 스펙 문서.

Kiro는 Easy Approach to Requirements Syntax의 약자인 EARS로 조건과 기대하는 시스템 동작을 표현합니다. 이 예시라면 “일반 멤버가 내보내기를 요청하면 시스템은 요청을 거부하고 내보내기 파일을 반환하지 않아야 한다”라고 쓸 수 있습니다. 이 정도로 구체적이면 테스트로 옮길 수 있습니다. Feature Specs 문서.

Kiro에는 Design-First와 Quick Spec도 있습니다. Design-First는 기술 설계에서 시작하고, Quick Spec은 중간 승인 단계 없이 문서를 생성합니다. 에이전트가 의도를 계속 잘못 이해하는 상황이라면 창업자는 Requirements-First를 선택하고 각 검토 단계를 활용하는 편이 좋습니다. 검토 지점을 없애면 바로 그 문제를 해결해 주는 절차도 사라집니다.

Steering은 .kiro/steering/ 아래에 지속적으로 참조할 Markdown 컨텍스트를 둡니다. 기본 파일은 product.md, tech.md, structure.md이며 각각 제품, 기술 스택, 저장소 구조를 다룹니다. IDE의 Generate Steering Docs로 이 초기 컨텍스트를 만들 수 있습니다. 생성된 내용은 실제 저장소와 대조해 검토합니다. “기존 멤버십 권한 정책을 재사용한다”가 여러 기능에 공통으로 적용된다면 여기에 넣고, “소유자만 내보낼 수 있다”는 내보내기 스펙에 넣습니다. Steering 문서.

Hooks는 이벤트가 발생하면 셸 명령이나 에이전트 프롬프트를 실행합니다. 현재 프로젝트 훅 파일의 경로는 .kiro/hooks/<id>.json이며, PostFileSave는 문서에 명시된 트리거입니다. 관련 소스가 바뀔 때 기존 내보내기 테스트를 실행하는 식으로 범위가 좁은 훅을 만들 수 있습니다. 제안된 코드 변경을 자동으로 검사하는 지속적 통합(CI)에도 같은 검사를 두어, 로컬 훅에서만 검증이 이루어지지 않게 합니다. Kiro의 현재 기능 지원 표에 따르면 훅은 IDE와 CLI에서 지원되며 Web이나 Mobile에서는 지원되지 않습니다. Hooks 문서.

한계: 자동으로 생성된 요구사항은 아무도 승인하지 않은 가정을 정식 규칙으로 굳힐 수 있습니다. 설계 전에 권한, 빈 결과, 실패 시 동작을 검토해야 합니다. 스펙 모드는 절차를 체계화하지만, 빠진 제품 판단까지 채워 주지는 않습니다.

Claude Code에서 스펙 주도 개발하기

Anthropic의 코딩 에이전트인 Claude Code에서도 기능 스펙과 Plan Mode를 이용해 이 절차를 따를 수 있습니다. 방식을 시험해 보기 위해 별도의 스펙 프레임워크를 설치할 필요는 없습니다.

specs/workspace-export/spec.md를 직접 작성하거나 에이전트가 만든 초안을 검토합니다. 그런 다음 계획 모드로 터미널 세션을 시작합니다.

claude --permission-mode plan

Claude에게 해당 파일을 읽고 내보내기와 관련된 기존 코드를 살펴본 뒤, 인수 기준에 연결된 구현 계획을 제안하도록 요청합니다. 구현을 승인하기 전에 미해결 질문과 실행하려는 구체적인 검증 항목도 받습니다.

Plan Mode는 조사하고 접근 방식을 제안하는 용도로 설계됐습니다. 다만 Anthropic은 권한 우회를 사용할 수 있는 대화형 터미널 세션에 예외가 있다고 명시합니다. 이 경우 계획 모드의 편집 차단이 적용되지 않습니다. 승인 전에는 변경하지 못하도록 하려면 우회 기능을 켜지 않은 상태로 시작해야 합니다. 권한 모드 문서.

제안을 검토한 뒤 승인한 접근 방식은 specs/workspace-export/plan.md에, 체크리스트는 tasks.md에 저장하고 구현을 허용합니다. 이 경로들은 이 글에서 제안하는 관리 방식이며, Plan Mode가 자동 생성을 보장하는 파일은 아닙니다. 제어 방법과 승인 후 전환 절차는 Claude Code Plan Mode 가이드에서 다룹니다.

지속적으로 적용할 저장소 지침은 팀 메모리 가이드를 참고해 CLAUDE.md에 두고, 특정 기능의 동작은 해당 스펙에 둡니다. 그렇지 않으면 일시적인 내보내기 요구사항이 영구 지침이 되어 관련 없는 작업에도 영향을 줄 수 있습니다.

한계: 대화에만 남겨 둔 계획은 잃어버리거나 이후 결정과 어긋나기 쉽습니다. 파일로 저장하더라도 후속 구현과 검토에서 명시적으로 참조해야 의미가 있습니다.

Codex에서도 같은 스펙 파일로 Plan Mode 활용하기

OpenAI의 코딩 에이전트인 Codex에서도 같은 방식으로 간단히 작업을 이어갈 수 있습니다. 작업을 실행 중이지 않은 CLI 채팅에서 /plan으로 계획을 시작하며, 같은 입력에 요청 내용을 함께 적을 수 있습니다. 공식 명령어 문서.

다음처럼 요청할 수 있습니다. “specs/workspace-export/spec.md를 읽어 주세요. 기존 멤버십 정책, 작업 조회 쿼리, 테스트를 살펴보세요. 모든 요구사항을 충족하는 최소한의 구현 계획을 제안하고, 구현 전에 아직 결정되지 않은 사항을 짚어 주세요.”

계획을 검토하고 합의한 파일을 저장한 다음, Codex에 작업 구현과 함께 각 요구사항을 어떤 테스트로 확인했는지 연결한 완료 보고서를 요청합니다. 지속적으로 적용할 저장소 지침에는 AGENTS.md를 사용하며, /init으로 기본 틀을 만들 수 있습니다. 초기 환경은 Codex CLI 설정 가이드에서 다룹니다.

OpenAI도 장기 작업에서 스펙, 계획, 진행 상황을 Markdown으로 관리하는 방식을 문서로 안내합니다. 다음 세션에서 합의 내용을 다시 열어 볼 수 있다는 점이 유용합니다. 한계: Plan Mode가 별도의 기능 스펙을 알아서 최신 상태로 유지하지는 않습니다. 변경 검토 절차에 스펙 갱신을 포함해야 합니다. OpenAI의 워크플로 문서.

스펙 주도 개발 예제: 워크스페이스의 작업을 CSV로 내보내기

레코드를 쉼표로 구분한 값으로 내려받는 작은 CSV 내보내기 기능만 봐도, 동작을 먼저 결정하면 왜 여러 파일을 다시 손보는 일을 줄일 수 있는지 알 수 있습니다. “CSV 내보내기를 추가해 줘”라고만 하면 에이전트가 사용자 역할, 데이터 범위, 페이지 처리, 파일 형식을 추측해야 합니다. 버튼이 보기 좋게 완성됐어도 이 모든 판단이 틀릴 수 있습니다.

아래는 기존 작업 관리 애플리케이션을 대상으로 한 설명용 예시입니다. 경로, 요구사항 ID, 제안하는 테스트는 이해를 돕기 위한 것이며, 이 글을 위해 실제 저장소에서 테스트하거나 머지했다는 뜻은 아닙니다.

한 페이지로 정리한 스펙

다음을 기능의 spec.md로 저장하거나, 같은 동작 요구사항을 Kiro의 requirements.md에 작성합니다.

R2에 담긴 결정을 눈여겨보면 “조건에 맞는 모든 결과”와 “지금 보이는 페이지”는 다릅니다. 구현 전에 이를 정하면 쿼리와 테스트 계획에 바로 반영할 수 있습니다. 데모 후에 결정하면 둘 다 다시 손봐야 할 수 있습니다.

R4에는 구체적인 예시로 결정해야 할 사항을 의도적으로 남겨 두었습니다. 스펙을 승인하기 전에 스프레드시트 수식으로 해석되는 입력을 어떻게 처리할지 정하고 예시를 기록합니다. “안전하게 내보낼 것”이라는 문장만으로는 에이전트가 대신 정책을 선택하게 됩니다.

설계: 기존 애플리케이션에 맞추기

설계에서는 기존 세션과 멤버십 정책을 재사용하고, 작업 목록의 필터 로직을 추출하거나 재사용하며, 목록 응답을 바꾸지 않고 내보내기 응답을 추가해야 합니다. 내보내기 요청은 서버의 권한 검사를 거치도록 합니다. 인증된 멤버십 정보를 근거로 접근 가능한 워크스페이스를 정한 뒤, 그 범위 안에서 요청한 필터를 적용합니다.

저장소에 이미 사용하는 CSV 직렬화 도구가 있다면 그것을 선택합니다. 콘텐츠 및 다운로드 헤더, 필드 안전 처리 정책, 오류 동작, 테스트를 명시합니다. 버튼도 애플리케이션의 기존 로딩 및 오류 상태를 활용해 추가합니다.

예상 결과 크기가 애플리케이션의 기존 요청 처리 및 메모리 제약 안에 들어오는지도 설계에서 확인해야 합니다. 모든 결과를 한 번에 내보낼 수 없다면 이 충돌을 기능 책임자에게 다시 가져갑니다. 범위를 제한한 내보내기로 할지, 백그라운드 처리를 별도 범위로 잡을지 결정합니다. 에이전트가 임의로 상한을 만들거나 R6에 어긋나는 작업 시스템을 조용히 추가해서는 안 됩니다.

작업 목록: 변경마다 검증 방법 붙이기

설계를 리뷰어가 확인할 수 있는 작업으로 바꿉니다.

1. 기존 작업 목록의 동작과 공통 필터 규칙을 회귀 검사로 남깁니다.
2. 소유자, 일반 멤버, 소유자 권한을 잃은 사용자, 다른 워크스페이스에 대한 요청 권한 테스트를 추가합니다.
3. 합의한 필드 정책에 따라 범위를 제한한 쿼리와 CSV 응답을 구현합니다.
4. 내보내기 UI, 로딩 상태, 실패 시 표시를 추가합니다.
5. 인수 검사를 마치고 diff에서 기능 범위를 벗어난 변경이 없는지 확인합니다.

이 목록은 이 예시를 나누는 한 가지 방식입니다. 툴킷이 다른 목록을 생성할 수도 있습니다. 판단 기준은 합의한 내용을 빠짐없이 다루는지입니다.

TypeScript 애플리케이션이라면 검토할 코드 변경에 권한 검사, 필터링, 응답을 담당하는 server/exports/tasks.ts, 사용자 상호작용을 담당하는 ui/tasks/ExportButton.tsx, 인수 사례를 확인하는 tests/task-export.test.ts가 포함될 수 있습니다. 이 경로는 설명용 예시이며, 프레임워크가 요구하는 규칙은 아닙니다. 새 큐 워커나 데이터베이스 마이그레이션이 추가됐다면 범위가 바뀌었다는 신호이므로 머지 전에 정리해야 합니다.

인수 기준에서 머지 판단까지

에이전트가 수정한 파일 목록보다 동작을 입증하는 근거를 요구해야 합니다. 풀 리퀘스트 설명에는 각 요구사항을 다음과 같은 검사와 연결해 적습니다.

리뷰어는 이 검사들을 스펙과 대조하고, 권한 및 쿼리 코드를 살펴보며, 프로젝트에서 통상적으로 쓰는 검토 환경에서 합의한 사용자 흐름을 직접 실행해야 합니다. 에이전트가 구현과 테스트를 모두 작성했다면 기대 결과는 독립적으로 검토합니다. 테스트도 코드와 똑같은 잘못된 가정을 충실히 확인하고 있을 수 있습니다.

예를 들어 검토 중 엔드포인트가 현재 페이지만 읽는다는 사실을 발견했다고 가정합니다. 기능 책임자가 여전히 조건에 맞는 모든 결과를 원한다면 R2는 유지하고 쿼리를 고친 뒤, 현재 페이지 밖에도 일치 항목이 있는 테스트를 추가합니다. 책임자가 범위를 바꾼다면 승인 전에 R2, 설계, 테스트를 함께 수정합니다.

검증 근거가 합의와 일치할 때 머지합니다. 검토한 스펙, 최종 설계, 완료된 작업 기록, 구현, 테스트를 같은 풀 리퀘스트에 포함합니다. 수용한 범위 변경도 그곳에 기록합니다. 머지 후에는 스펙을 현재 유효한 기준으로 유지하거나, 과거 기능 기록임을 표시합니다. 오래된 스펙이 여전히 공식 기준처럼 보이면 다음 혼란의 원인이 됩니다.

이 방식의 이점은 권한과 페이지 처리에 관한 가정이 구현 전반으로 퍼지기 전에 결정을 마치는 데서 나옵니다. 머지한 뒤에도 스펙, 테스트, 코드에 같은 결정이 남습니다.

비용은 얼마나 들고, 언제 본전을 뽑을까요?

이 방식에는 검토와 유지 관리 시간, 그리고 초안 작성과 구현에 사용하는 에이전트 비용이 듭니다. Spec Kit은 오픈 소스이지만 연결하는 코딩 에이전트에는 별도의 이용 조건이 적용됩니다. 일반 Markdown 파일에는 별도의 스펙 도구 구독료가 들지 않지만, 모델 사용까지 무료가 되는 것은 아닙니다.

Kiro의 표준 상용 요금은 적용 세금 별도로 Free가 월 $0에 50 크레딧, Pro가 사용자당 월 $20에 1,000 크레딧입니다. 따라서 Pro를 네 명이 구독하면 추가 크레딧과 세금 별도로 4 × $20 = 월 $80입니다. 이는 사용자 수에 따른 단순 요금 계산이며, 구현할 수 있는 기능 수를 예측한 값은 아닙니다. Kiro 공식 요금 페이지.

추가 유료 크레딧은 개당 $0.04입니다. Kiro는 스펙 구체화, 작업 실행, 에이전트 훅 실행에 크레딧이 사용되며, 복잡한 스펙 작업에는 크레딧 하나보다 많이 들 수 있다고 설명합니다. 실제 작업량을 관찰하지 않고 “크레딧”을 “완성한 기능 수”로 환산할 근거는 없습니다. Kiro 크레딧 설명.

경제성을 판단하는 기준은 간단합니다. 기능 명세, 검토, 유지 관리에 추가로 드는 비용이 그 덕분에 피한 재구현 비용보다 작아야 합니다. 실제 개발 과정에서 이 비용을 기록해 봅니다. 문서만 늘고 같은 결정을 여전히 코드 리뷰 때까지 미룬다면 추가 부담을 정당화하지 못한 것입니다.

과장된 기대는 무엇이며, 언제 과한 절차가 되나요?

문서를 충분히 자세히 쓰면 에이전트가 안정적으로 정답을 낸다는 기대는 과장입니다. 스펙 자체가 틀릴 수 있고, 구현이 스펙을 무시할 수 있으며, 테스트가 잘못된 가정을 그대로 반복할 수도 있습니다.

구분해야 할 것은 글로 적은 의도와 실제로 강제되는 동작입니다. 요구사항은 일반 멤버가 내보낼 수 없다고 말하고, 서버의 권한 검사와 테스트는 그 규칙이 지켜지게 합니다. 요구사항 체크리스트가 확인하는 것은 설명의 품질입니다. 애플리케이션을 실행하는 것은 아닙니다. 둘을 같은 것으로 취급하면 근거 없는 확신이 생깁니다.

문서와 구현이 어긋나는 것도 실패 원인입니다. 개발자가 권한 동작을 바꾸면서 코드만 수정하면 다음 에이전트가 오래된 스펙에 맞춰 애플리케이션을 다시 “고칠” 수 있습니다. 동작이 바뀔 때는 관련 합의도 갱신하거나, 그 합의를 더 이상 유효하지 않은 기록으로 명확히 보관해야 합니다. 오래 남는 컨텍스트는 정확성을 유지할 때에만 도움이 됩니다.

에이전트가 권한, 예외 상황, 연동, 인수 기준을 반복해서 놓친다면 지금 적용합니다. 모호한 요구사항이 여러 구성 요소나 리뷰어에게 영향을 주는 기능에 이 절차를 사용합니다.

누군가 그 기능을 원하는지부터 알아보는 단계라면 정식 스펙 작성은 미룹니다. 버릴 수 있는 프로토타입을 만들거나 불확실한 부분부터 조사합니다. 검증되지 않은 아이디어에 정교한 명세를 붙이면 잘못된 투자도 이미 확정된 결정처럼 느껴질 수 있습니다.

오탈자, 기존 스타일에 맞춘 조정, 명확한 회귀 테스트로 확인할 수 있는 좁은 범위의 버그처럼 의도와 영향 범위가 분명하다면 작은 수정은 작게 처리합니다. 원하는 동작을 적고 검증하면 됩니다. 프로젝트 원칙부터 설계와 작업 분할까지 모든 단계를 거치면 변경 자체보다 더 많은 주의와 시간을 들일 수 있습니다.

판단 기준은 코드 줄 수가 아닙니다. 그 절차가 없을 때 에이전트가 중요한 가정을 얼마나 많이 스스로 내려야 하는지가 기준입니다.

스펙 주도 개발, 첫 주에는 이렇게 시작합니다

백로그에 이미 있는 작은 기능을 고릅니다. 제외 범위와 실패 상황을 포함한 한 페이지짜리 동작 명세를 기능 책임자가 승인하게 합니다. 현재 에이전트의 계획 모드나 Spec Kit, Kiro의 해당 절차를 이용해 저장소의 실제 구조에 근거한 설계를 제안받습니다.

구현 전에 질문부터 검토합니다. 요구사항과 연결된 작업 목록을 요청합니다. 풀 리퀘스트에서는 같은 합의를 기준으로 검증 근거를 확인하고, 바뀐 결정을 기록합니다. 절차의 무게는 해소해야 할 모호함에 맞춥니다.

AI로 제품을 만들고 운영하는 실용적인 방법을 받아 보려면 뉴스레터를 구독하세요.