AI 에이전트와 함께하는 스펙 주도 개발 풀코스

URL: https://www.youtube.com/watch?v=FJo7p9SPS9c
날짜: 2026-09-24
채널: Tech Bridge
원문 제목: [한영자막] AI 에이전트와 함께하는 스펙 주도 개발 풀코스 강의
원강좌: DeepLearning.AI × JetBrains, Paul Everitt 강의

---

📌 핵심 질문 / 이 강좌가 다루는 핵심 논점

==AI 코딩 에이전트의 속도를 유지하면서도 사람이 제품 의도와 품질을 통제하려면, 프롬프트가 아니라 지속되는 명세(spec)를 중심으로 개발해야 한다.==

• 프로젝트 헌법(constitution)이 미션·기술 스택·로드맵을 고정해 에이전트가 매 세션 같은 원칙을 적용하게 한다.
• 기능마다 명세 작성 → 구현 → 검증을 반복하고, 기능 사이에 재계획(replanning)을 넣어 코드·명세·제품 결정을 동기화한다.
• 명세는 작은 문장 변경을 수백 줄의 구현에 전파하고, 세션 간 컨텍스트 손실과 의도 이탈을 줄이는 영속적 계약이 된다.

Vibe coding은 “버튼을 만들어 달라”처럼 높은 수준의 요청을 던지고 결과를 보며 대화로 수정하는 방식이다. 단순한 버튼에는 쓸 수 있지만 대화 기록이 영속적 산출물이 되지 않고, 프로젝트가 커질수록 기술 부채와 일회성 코드가 쌓인다. 스펙 주도 개발(Spec-Driven Development, SDD)은 사람이 무엇(what)과 왜(why)를 명세하고 에이전트가 어떻게(how)를 구현하게 하며, 에이전트를 빠른 기술 지식을 가진 페어 프로그래머, 사람을 설계도와 최종 책임을 가진 수석 아키텍트로 배치한다.

1. Vibe coding에서 스펙 주도 개발로

SDD의 중심은 에이전트에게 더 긴 프롬프트를 주는 일이 아니라, 사람이 알고 있지만 에이전트가 모르는 맥락을 재사용 가능한 문서로 만드는 일이다.

1.1. Vibe coding이 복잡한 프로젝트에서 무너지는 이유

1. 결과를 보며 고치는 대화형 루프

   1. “버튼을 만들어 달라”는 요청은 빠르게 결과를 만들지만, 결과가 크기·동작·스타일의 중요한 부분에서 어긋날 수 있다.
   2. 사용자는 잘못된 점을 계속 지적하고 에이전트는 다시 시도하지만, 긴 대화 기록은 다음 세션의 영속적 설계 문서가 되지 않는다.

2. 결정의 무작위 위임

   1. 명세가 없으면 제품 범위, 기술 아키텍처, 데이터베이스, 품질 기준을 에이전트가 빈칸 채우기 방식으로 결정한다.
   2. 여러 개발자가 각기 다른 에이전트를 지휘하면 빠른 구현이 서로 모순되는 방향으로 진행되어 유지보수와 통합 단계에서 문제가 폭발한다.

3. 속도와 엔지니어링의 교환

   1. 한 번의 짧은 프롬프트로 충분한 작업은 가볍게 처리해도 되지만, 에이전트가 20~30분 동안 코드를 작성할 복잡한 작업은 사람이 3~4분 동안 명확한 지시를 쓰는 편이 전체 비용이 낮다.
   2. 문제의 핵심은 AI 사용 자체가 아니라 감독되지 않은 AI 생성으로 인해 제품 의도와 구현이 분리되는 현상이다.

1.2. 명세가 제공하는 세 가지 레버리지

1. 작은 문장으로 큰 변경 통제

   1. “SQLite와 Prisma ORM을 사용하라”는 한 문장이 수백 줄의 코드와 설정으로 증폭된다.
   2. 같은 문장을 MongoDB로 바꾸면 downstream 구현 전체가 같은 방향으로 바뀌므로 코드를 직접 고치는 것보다 명세 수정의 레버리지가 크다.

2. 컨텍스트 decay 방지

   1. 에이전트는 상태가 없고 세션이 길어지면 컨텍스트 윈도우가 차며, 핵심 제약을 잊거나 더 많은 실수를 한다.
   2. 명세는 세션과 에이전트가 바뀌어도 남아 있는 프로젝트 기억으로 작동해 매번 비협상 조건을 다시 추론하지 않게 한다.

3. 의도 충실도(intent fidelity) 향상

   1. 문제, 성공 기준, 제약, 사용자 흐름을 먼저 명시하면 에이전트가 구현 계획을 확장하더라도 목표에서 벗어날 가능성이 줄어든다.
   2. 명세는 사람과 사람 사이의 계약인 동시에 사람과 에이전트 사이의 계약이며, 이해하기 쉬운 인간 언어로 작성되어 이해관계자도 검토할 수 있다.

1.3. 코딩 에이전트와 챗봇의 역할 차이

1. 코딩 에이전트의 실행 범위

   1. 챗봇은 코드를 말로 논의하지만 프로젝트 코드와 설치된 도구에 접근하지 못한다.
   2. 에이전트는 요청을 받아 계획을 세우고 추론하며, 코드베이스와 개발 도구를 사용해 결과까지 이끈다.

2. 역할 분담

   1. 에이전트는 기술 지식과 구현 속도를 제공하는 근육이다.
   2. 사람은 장기 목표와 트레이드오프를 결정하고 청사진을 제공하는 두뇌이자 설계자다.

2. SDD의 전체 운영 모델

프로젝트 수준의 헌법과 기능 수준의 반복 루프를 분리하면, 장기 원칙과 단기 구현을 동시에 관리할 수 있다.

2.1. 프로젝트 헌법(constitution)

1. 미션(mission)

   1. 프로젝트의 비전, 핵심 아이디어, 대상 사용자, 범위와 이해관계자의 기대를 기록한다.
   2. 미션은 기능을 추가할 때마다 “무엇을 만들 수 있는가”보다 “왜 만들어야 하는가”를 판단하는 기준이 된다.

2. 기술 스택(tech stack)

   1. 팀이 사용하는 언어, 프레임워크, 배포 방식, 데이터베이스와 제약을 기록해 에이전트와 개발자의 공통 기반을 만든다.
   2. 기술 스택은 모든 저수준 구현을 고정하는 문서가 아니라, 에이전트가 스스로 결정해도 되는 영역과 지켜야 할 경계를 구분하는 문서다.

3. 로드맵(roadmap)

   1. 로드맵은 기능을 순서가 있는 작은 단계로 나누고 각 단계를 독립적인 feature spec 프로세스로 연결한다.
   2. 로드맵은 살아 있는 문서이므로 기능을 끝낼 때 다음 단계가 여전히 제품에 맞는지 다시 판단한다.

4. 대안적 표현

   1. AGENTS.md 같은 최상위 규칙 파일도 프로젝트 수준의 지침을 담을 수 있다.
   2. constitution은 특정 에이전트에 묶이지 않고 미션·스택·로드맵을 구조적으로 표현한다는 점에서 에이전트 중립적이다.

2.2. 기능 개발 루프

1. Plan

   1. 새 브랜치와 깨끗한 에이전트 컨텍스트에서 기능의 범위, 요구사항, 작업 계획, 검증 점수표를 대화로 정한다.
   2. 사람은 에이전트가 제시한 선택지를 그대로 수락하지 않고 버전, 타입 엄격성, 데이터베이스, 사용자 경험과 같은 핵심 결정을 직접 확정한다.

2. Implement

   1. 확정된 세 문서가 요구하는 작업 그룹을 에이전트가 구현하며, 큰 기능은 작업 그룹 단위로 나누어 작은 커밋을 만든다.
   2. 구현 중에는 콘솔의 변경 내역과 최종 요약을 관찰해 사람이 무엇이 바뀌었는지 계속 파악한다.

3. Validate

   1. 애플리케이션 실행, 테스트, 디버거 탐색, 명세와 구현의 대조를 함께 수행해 기능이 동작하고 이해 가능한 상태인지 확인한다.
   2. 검증은 에이전트에게 맡기는 자동 점검과 사람이 직접 책임지는 고수준 리뷰를 결합한다.

4. Replan

   1. 기능 사이에 헌법, 로드맵, 테스트 정책과 개발 프로세스를 갱신한다.
   2. 작은 변경은 재계획 브랜치에서 직접 반영할 수 있지만, 큰 새 작업은 로드맵에 별도 기능 단계로 등록한다.

2.3. 적절한 세부 수준과 브랜치 운영

1. 무엇을 명시할 것인가

   1. 목표, 미션, 대상 사용자, 성공 기준, 제약과 중요한 트레이드오프처럼 에이전트가 알 수 없는 맥락은 자세히 쓴다.
   2. 변수 이름이나 모든 CSS 클래스처럼 에이전트가 합리적으로 결정할 수 있는 저수준 선택은 과도하게 고정하지 않는다.

2. 건축가와 시공자의 비유

   1. 사람은 건물의 설계도와 인수 기준을 만들고, 에이전트는 설계에 맞춰 시공한다.
   2. 사람의 역할은 시공 방법을 일일이 지시하는 것이 아니라 설계하고 감독하고 결과를 검토해 수정시키는 일이다.

3. 버전 관리

   1. 각 기능은 별도 브랜치에서 명세를 먼저 커밋하고 구현·검증·최종 커밋을 거쳐 main에 병합한다.
   2. 작은 커밋은 리뷰 범위를 줄이고 어떤 명세가 어떤 코드 변경을 만들었는지 추적하기 쉽게 한다.

3. AgentClinic으로 만드는 그린필드 프로젝트

실습 프로젝트 AgentClinic은 인간 때문에 스트레스를 받는 AI 에이전트를 위한 패러디형 풀스택 애플리케이션이다.

3.1. 작업 환경과 책임

1. 권장 조합

   1. WebStorm IDE, Claude Code 에이전트, TypeScript, Git 저장소로 새 프로젝트를 시작한다.
   2. SDD는 특정 IDE나 에이전트에 종속되지 않으므로 VS Code와 Codex CLI, Zed와 로컬 모델 같은 조합도 동일한 원칙을 적용할 수 있다.

2. 명령 실행 승인

   1. Claude Code는 명령을 실행할 때 확인을 요청하며, 세션 전체 승인이나 안전하지 않은 모드를 선택할 때는 보안 트레이드오프를 이해해야 한다.
   2. 어떤 명령과 코드가 실행되는지의 최종 책임은 에이전트가 아니라 개발자에게 있다.

3.2. AgentClinic 헌법 만들기

1. 제품 개념

   1. AgentClinic은 Next.js 백엔드와 React 프런트엔드를 가진 웹 앱으로, 예약·질환·치료를 관리한다.
   2. 질환에는 환각(hallucination), 컨텍스트 부패(context rot), 기억 문제와 서브에이전트 협업 스트레스가 포함되고, 치료에는 컨텍스트 주입(context infusion) 같은 유머러스한 항목이 들어간다.

2. 에이전트와의 인터뷰

   1. 저장소의 README.md에 이해관계자 의견을 넣고, 에이전트에게 미션·기술 스택·로드맵을 함께 작성하라고 요청한다.
   2. 미션의 어조는 장난스럽게 정하고, 백엔드는 팀이 익숙한 TypeScript로 지정하며, 로드맵은 사람이 검토할 수 있는 작은 단계로 나눈다.

3. 검토와 수정

   1. 결과는 specs/mission.md, specs/tech-stack.md, specs/roadmap.md 세 파일로 저장된다.
   2. 미션에 대상 사용자가 빠지면 직접 파일을 편집하지 않고 에이전트와 대화해 관련 문서를 함께 수정한다.
   3. 빠른 프로토타입에 맞춰 SQLite를 선택하고, 에이전트가 추천한 내용을 검토한 뒤 헌법을 커밋한다.

4. 첫 기능의 계획·구현·검증

첫 로드맵 항목인 “Hello Hono”는 작은 기능으로 SDD의 전체 루프를 보여준다.

4.1. 기능 명세 작성

1. 새 컨텍스트와 브랜치

   1. 에이전트가 헌법에서 프로젝트 맥락을 다시 읽도록 새 세션을 열고, 기능 전용 브랜치에서 작업한다.
   2. 프롬프트는 기능 범위, 요구사항, 작업 계획과 검증 점수표를 만들도록 요청한다.

2. 사람이 확정한 결정

   1. 1단계 범위는 로드맵에 적힌 그대로 유지한다.
   2. Hono 버전을 고정하고 strict TypeScript를 강제하며, 수동 curl 호출을 기본 검증으로 선택한다.

3. 문서 리뷰

   1. 계획을 검토한 뒤 첫 화면에 보기 좋은 placeholder 페이지가 필요하다는 의도를 추가한다.
   2. 변경은 계획·요구사항·검증 문서 전체에 반영되어야 하며, 변수 이름 같은 사소한 구현 세부사항은 사람의 통제 범위에 넣지 않는다.

4.2. 구현과 첫 번째 사람 검증

1. 작업 그룹 구현

   1. /clear로 이전 대화를 비우고 세 문서에 정의된 모든 작업 그룹을 구현하도록 요청한다.
   2. 보안이나 데이터베이스처럼 작은 실수가 뒤에서 누적되는 영역은 작업 그룹을 더 잘게 나누고 커밋을 자주 만든다.

2. 실행 결과 확인

   1. 에이전트가 코드와 자체 검증을 마치면 package.json의 실행 명령으로 서버를 시작한다.
   2. 브라우저에 최소한의 화면이 나타나는지 확인하며, 작은 결과라도 명세가 실제 픽셀로 이어졌는지 확인한다.

3. 고수준 코드 리뷰

   1. 에이전트가 만든 Home.tsx가 지나치게 작다는 사실을 발견하고 header·main·footer 랜드마크를 가진 레이아웃과 CSS 파일을 요구한다.
   2. 구현의 부족함이 계획의 부족함에서 비롯되었으므로 코드만 고치지 않고 명세와 계획도 함께 수정한다.

4.3. 드리프트와 인지 부채 관리

1. 인간을 루프에 남겨두기

   1. 에이전트가 빠르게 작성하는 만큼 사람은 기능이 명세에 맞는지 고수준에서 검토해야 한다.
   2. 인지 부채는 코드가 무엇을 하고 어떻게 변했는지 사람이 추적해야 하는 정신적 부담이므로, 변경 크기를 관리 가능한 수준으로 유지해야 한다.

2. 문서 동기화

   1. 세 개의 하위 컴포넌트를 한 파일에 넣은 결과가 팀의 관례와 어긋나면 IDE의 이동 도구로 파일을 나눌 수 있다.
   2. 하지만 사람이 직접 파일을 옮기면 다른 명세·README·아티팩트가 낡을 수 있으므로 에이전트에게 모든 참조를 갱신하게 한다.

3. 테스트의 공백

   1. 첫 기능에서는 테스트 패키지가 설치되지 않았음을 발견하고, 모든 기능에 적용할 테스트 정책을 다음 재계획 단계로 미룬다.
   2. 헌법의 작은 업데이트는 기능 브랜치와 함께 둘 수 있지만, 큰 헌법 변경은 어떤 버전이 어떤 코드를 만들었는지 추적하기 위해 별도 브랜치로 분리한다.

5. 재계획과 두 번째 기능

기능을 연속으로 추가하기 전에 프로젝트와 작업 방식을 잠깐 멈춰 재검토하면 장기 속도가 빨라진다.

5.1. 테스트와 제품 결정 갱신

1. 테스트 정책의 헌법 반영

   1. 첫 기능에서 빠진 테스트 선호도를 기술 스택과 헌법에 추가하고, 테스트 프레임워크 설정과 실행 스크립트를 만든다.
   2. 에이전트가 기존 기능용 테스트를 직접 작성하게 한 뒤 IDE의 디버거로 실행해 사람도 코드 흐름을 탐색한다.

2. 모바일 우선 요구사항

   1. 사용자 40%가 모바일을 사용한다는 제품 관리자 피드백을 받으면 반응형 디자인을 제품 명세·기능 명세·코드에 동시에 반영한다.
   2. 초기의 작은 조정은 재계획에서 직접 구현할 수 있지만, 큰 반응형 작업은 별도 로드맵 기능으로 승격한다.

3. 로드맵 재정렬

   1. 다음 항목을 검토한 결과 기능 2·3·4·5가 서로 결합되어 한 단계로 다루는 편이 낫다고 판단한다.
   2. 재계획은 현재 기능 하나뿐 아니라 전체 프로젝트, 조직의 공통 개발 프로세스까지 대상으로 삼을 수 있다.

5.2. 반복 업무를 스킬로 패키징

1. 변경 로그 스킬

   1. main 병합 때마다 비기술 이해관계자와 에이전트가 읽을 CHANGELOG를 갱신하는 반복 절차를 스킬로 만든다.
   2. 에이전트의 스킬 생성기를 사용해 작성하고 프로젝트 전용인지 전역 표준인지 결정한다.

2. 검증 스킬

   1. README 갱신, 린트, 포맷, 테스트 작성과 실행 같은 반복 검증을 하나의 검증 스킬로 묶을 수 있다.
   2. 전역 스킬 영역에 저장하면 여러 프로젝트에서 재사용할 수 있고, 프로젝트에만 필요한 규칙은 로컬에 둔다.

5.3. 두 번째 기능의 구현과 AI fatigue

1. 시작 전 상태 점검

   1. 미완료 작업이 없는지, 직전 브랜치가 main에 병합됐는지, 다음 로드맵 항목이 여전히 맞는지 확인한다.
   2. 이전 에이전트 컨텍스트를 지워 명세가 기억의 스냅샷이 아니라 의도를 담도록 하고, 새 기능에 컨텍스트 예산을 집중한다.

2. 명세와 구현

   1. 여러 관련 기능을 한 phase로 처리하기로 한 결정, 마이그레이션에 plain SQL을 쓸 결정, 선택한 검증 항목을 프롬프트에 명시한다.
   2. CSS 프레임워크로 PicoCSS를 쓰도록 세 feature spec 파일에 반영하고, 명세를 커밋한 뒤 구현한다.

3. 리뷰의 초점

   1. 에이전트가 만든 대량의 코드를 모두 같은 깊이로 읽기보다, 제품 요구사항을 만족하고 개발자의 이름으로 커밋할 수 있는지에 집중한다.
   2. inline props 타입을 독립 TypeScript 타입으로 분리하는 식의 발견은 처음 명세에 없었더라도 실패가 아니라 명세를 발전시키는 학습이다.

4. 깊은 검증과 기능 경계

   1. 애플리케이션을 실행하고 테스트를 읽으며, 필요하면 여러 서브에이전트에게 전체 프로젝트와 새 기능을 깊이 리뷰하게 해 주 에이전트의 컨텍스트를 보존한다.
   2. 서브에이전트의 이슈와 권고를 반영하고 테스트·수정을 마친 뒤 기능 브랜치를 커밋하고 병합한다.
   3. 기능 phase 사이의 깨끗한 경계는 사람이 검토해야 할 변화량을 줄여 AI fatigue를 낮추고, 다음 작업을 시작할 수 있는 흐름 상태를 회복시킨다.

6. MVP 실험과 레거시 프로젝트 적용

SDD는 새 프로젝트에만 쓰는 절차가 아니라, 기존 코드의 기억을 복원하고 이후 변경을 통제하는 방식이기도 하다.

6.1. 완성된 명세로 MVP 만들기

1. 큰 구현을 허용하는 조건

   1. 헌법과 기능 명세의 품질에 자신이 있고 결과를 검토·검증할 수 있을 때만 남은 로드맵을 한 번에 구현하도록 요청한다.
   2. 큰 구현은 정상적인 작은 기능 루프를 생략하는 특례가 아니라, 지금까지 만든 명세가 의도를 보존하는지 시험하는 극단적 실험이다.

2. MVP 결과 평가

   1. 에이전트의 질문에 답하고 남은 로드맵의 명세·계획·요구사항·검증을 디스크에 기록한 뒤 작은 planning 커밋을 만든다.
   2. 데이터베이스에서 조회한 샘플 데이터가 각 섹션을 채우는 데모가 나오면 MVP를 이해관계자에게 보여줄 수 있다.
   3. 명세 검증은 계획의 빈틈과 에이전트가 임의로 채운 잘못된 가정을 드러내며, 결과가 의도와 다르면 책임 있게 재계획해야 한다.

6.2. 레거시 코드에 헌법을 역설계하기

1. 기존 프로젝트의 시작점

   1. AgentClinic을 명세 폴더 없이 main 브랜치에서 새 Claude Code 세션으로 열어 레거시 프로젝트처럼 만든다.
   2. 실제 레거시 프로젝트에는 issue tracker, 스프레드시트, Word 문서, README, TODO처럼 과거의 제품 계획과 미완료 작업이 흩어져 있을 수 있다.

2. 역공학 과정

   1. 에이전트에게 기존 코드와 문서를 탐색해 미션·기술 스택·로드맵을 역설계하도록 요청한다.
   2. 기술 스택에는 프로젝트 구조와 프레임워크 버전이, 로드맵에는 TODO.md의 phase가 반영된다.

3. 변경 통제

   1. 생성된 헌법 파일을 커밋하면 과거 개발자가 만든 코드와 미래 에이전트의 변경을 연결하는 SDD 기반이 생긴다.
   2. 다음 기능인 phase one feedback form을 별도 브랜치에서 계획·검토·구현·검증하고 main에 병합한다.
   3. 명세는 프로젝트의 기억이 되어 시간이 지나도 설계 의도가 흐려지지 않게 한다.

7. 워크플로 자동화와 도구 생태계

반복되는 프롬프트와 검증을 스킬·CLI·표준으로 패키징하면 팀의 방식에 맞는 SDD를 여러 프로젝트와 에이전트에 이식할 수 있다.

7.1. Agent Skills와 progressive disclosure

1. 사용자 정의 스킬

   1. “이 작업을 하고 세 파일을 써라”처럼 기능 명세를 시작할 때마다 반복하는 프롬프트를 에이전트의 스킬 생성기로 자동화한다.
   2. 스킬은 프로젝트 단위나 전역 단위로 둘 수 있고, 프롬프트에서 이름을 언급하거나 다른 스킬이 호출하게 할 수 있다.

2. 호출 방식

   1. Agent Skills 표준은 스킬 설명을 읽고 필요한 시점에 호출하는 progressive disclosure를 사용한다.
   2. 에이전트의 판단은 컨텍스트가 커질수록 틀릴 수 있으므로 반드시 쓸 스킬을 아는 경우 프롬프트에 이름을 명시하는 편이 안정적이다.

3. 연구 백로그

   1. 기능을 멈추지 않고 데이터베이스 선택 같은 아이디어를 탐구하려면 연구 대화를 잘 알려진 위치의 보고서 파일로 저장한다.
   2. 나중에 해당 보고서 링크와 함께 로드맵에 연구를 예약하고, 연구 절차 자체도 스킬로 자동화할 수 있다.

7.2. MCP에서 CLI + Skills로

1. MCP의 역할

   1. Model Context Protocol은 API, 사설 지식 기반, 데이터베이스와 같은 외부 도구를 에이전트에 연결하는 보편적 확장 방식이다.
   2. Context7은 패키지의 최신 문서를 컨텍스트에 넣어 React 9.0이 아니라 React 9.2 이상의 정보를 참고하게 하는 대표 사례다.

2. CLI와 스킬의 장점

   1. Context7은 MCP 서버 대신 CLI 도구를 스킬에서 호출하는 선택지를 제공하며, 설치가 간단하고 행동을 직접 수행하면서 컨텍스트 사용량을 줄일 수 있다.
   2. MCP 서버가 사라진다는 뜻은 아니지만, 규모가 커질수록 CLI + Skills 조합이 같은 목적을 더 우아하게 달성할 수 있다는 흐름이 나타난다.

3. 플러그인과 신뢰

   1. Claude Code 같은 에이전트의 플러그인은 여러 확장을 묶어 설치·업데이트하는 방식이며, 무료 커뮤니티 플러그인이 늘고 있다.
   2. 플러그인은 아직 에이전트 간 표준이 아니고 코드를 실행할 수 있으므로 설치와 업데이트 때 신뢰할 수 있는 출처인지 확인해야 한다.

7.3. 표준 SDD 도구의 선택

1. GitHub Spec Kit

   1. Spec Kit은 constitution, plan, tasks, implement 명령으로 에이전트 중심의 스펙 주도 흐름을 형식화한다.
   2. 브랜치 관리, 검증 스크립트와 의견이 반영된 명세 문서 형식을 제공한다.

2. OpenSpec

   1. Fission AI의 OpenSpec은 propose → explore → apply → archive 흐름을 사용한다.
   2. propose와 explore는 plan에, apply는 implement에, archive는 replanning에 대응하며 빠른 기능을 위한 정규 패턴도 제공한다.

3. 도입 원칙

   1. 기존 프레임워크를 그대로 따르거나 프로젝트에 맞춰 스킬로 커스터마이즈할 수 있다.
   2. 중요한 것은 도구 이름이 아니라 팀의 결정과 검증을 지속 가능한 명세와 반복 루프로 남기는 일이다.

8. 에이전트 교체 가능성과 표준

명세가 특정 모델·IDE·에이전트에 묶이지 않으면 도구가 빠르게 변해도 프로젝트의 작업 방식과 산출물을 보존할 수 있다.

8.1. 서로 다른 확장 표준

1. MCP: 외부 도구와 지식원을 연결한다.
2. AGENTS.md: 에이전트가 따라야 할 프로젝트 규칙을 전달한다.
3. Agent Skills: 반복 워크플로와 추가 컨텍스트를 패키징한다.
4. ACP(Agent Client Protocol): 에이전트와 IDE·클라이언트를 연결한다.

8.2. Codex와 JetBrains에서의 교체

1. 워크플로 이식

   1. Claude Code용 기능 명세 스킬을 Codex의 다른 저장 경로로 복사해도 SDD 흐름 자체는 정상적으로 실행된다.
   2. 같은 프로젝트에서 에이전트를 오가며 작업해도 명세·규칙·검증 절차가 공통 계약으로 남는다.

2. ACP 레지스트리

   1. ACP는 에이전트와 클라이언트를 연결하고, ACP Registry는 검색·설치·연결의 전체 생명주기를 자동화한다.
   2. JetBrains IDE의 AI Chat에서 호환 에이전트를 찾고, OpenCode 같은 오픈소스 에이전트를 설치해 기존 에이전트와 같은 편집기에서 사용할 수 있다.

3. 표준의 확장성

   1. ACP 구조는 Language Server Protocol(LSP)에서 사용된 방식과 닮았고, 다음 편집 제안(Next Edit Suggestion)과 plan mode까지 다룬다.
   2. 필요하면 직접 커스텀 에이전트를 작성해 로컬 도구에 설치할 수도 있다.

8.3. 에이전트 선택 기준

1. 모델과 제품은 빠르게 바뀌므로 벤치마크 리더보드의 순위만 영구적인 기준으로 삼으면 안 된다.
2. 팀이 중시하는 비용, 속도, 코드 품질, 도구 접근성과 검증 가능성을 기준으로 판단하고 최신 평가를 계속 확인한다.
3. 명세는 에이전트보다 높은 추상화 계층에 있으므로 교체 가능한 도구를 사용해도 미션·기능·검증의 일관성을 유지한다.

주요 발언 모음

“에이전트는 근육이고, 명세는 두뇌다.”

“스펙은 세션과 에이전트 사이에 남아 프로젝트의 핵심 컨텍스트를 고정한다.”

“빨리 달리려면 천천히 달려야 한다.”

“오늘 작성한 스펙은 내일 프로젝트의 기억이 된다.”

“최고의 코드는 훌륭한 스펙에서 시작한다.”

핵심 데이터 & 수치

• 20~30분: 에이전트가 복잡한 구현에 투입할 수 있는 시간이며, 사람의 3~4분 명세 작성이 그 작업의 방향을 크게 좌우한다.
• 40%: 모바일 사용자가 차지하는 비중으로, 재계획에서 반응형 디자인을 제품·기능 명세와 코드에 함께 반영하는 근거가 된다.
• 3개: AgentClinic의 초기 헌법 파일인 mission.md, tech-stack.md, roadmap.md의 수다.
• 3단계: SDD의 반복 기능 루프인 Plan → Implement → Validate다.
• 4개: 프로젝트의 교체 가능성을 돕는 핵심 표준 축인 MCP, AGENTS.md, Agent Skills, ACP다.

결론 및 시사점

1. 복잡한 AI 코딩 작업은 짧은 프롬프트의 속도보다 사람의 의도와 품질을 지속시키는 명세의 품질이 좌우한다.
2. 프로젝트 헌법은 미션·스택·로드맵을 고정하고, 기능 명세는 요구사항·계획·검증을 구체화한다.
3. 구현 전후에 사람의 고수준 리뷰를 넣고, 테스트·실행·디버거·서브에이전트 리뷰를 결합하면 인지 부채와 AI fatigue를 줄일 수 있다.
4. 기능마다 별도 브랜치와 작은 커밋을 사용하고, 기능 사이의 재계획에서 제품 결정과 명세·코드의 드리프트를 바로잡아야 한다.
5. 그린필드에서는 대화로 헌법을 만들고, 브라운필드에서는 기존 코드·README·TODO·문서를 탐색해 헌법을 역설계하면 된다.
6. 반복 프롬프트와 검증은 Agent Skills로 묶고, MCP·CLI·Spec Kit·OpenSpec을 팀의 요구에 맞게 조합하면 SDD를 운영 체계로 확장할 수 있다.
7. 명세를 에이전트 중립적인 계약으로 유지하면 Claude Code, Codex, OpenCode와 IDE를 바꾸어도 개발 방식과 프로젝트 기억을 보존할 수 있다.

핵심 요약 (20줄)

1. 스펙 주도 개발은 사람이 무엇과 왜를 명세하고 AI 코딩 에이전트가 어떻게를 구현하게 하는 방식이다.
2. Vibe coding은 단순한 버튼에는 빠르지만 복잡한 프로젝트에서 일회성 코드와 기술 부채를 키운다.
3. 명세의 한 문장 변경은 수백 줄의 구현에 전파되어 코드 직접 수정보다 큰 레버리지를 만든다.
4. 영속적인 명세는 세션이 바뀌어도 핵심 제약을 보존해 에이전트의 컨텍스트 부패를 줄인다.
5. 문제와 성공 기준과 제약을 먼저 정의하면 에이전트가 사람의 의도에 맞는 결과를 만들 가능성이 높아진다.
6. 코딩 에이전트는 코드와 도구를 사용하지만 챗봇은 프로젝트를 실행할 수 없다는 점에서 역할이 다르다.
7. 프로젝트 헌법은 미션과 기술 스택과 로드맵을 기록하는 에이전트 중립적 기반 문서다.
8. 기능 개발은 별도 브랜치에서 계획하고 구현하고 검증하는 반복 루프로 진행한다.
9. 기능 사이의 재계획은 헌법과 로드맵과 테스트 정책과 프로세스를 최신 결정에 맞게 고친다.
10. AgentClinic은 인간 때문에 스트레스를 받는 AI 에이전트를 치료하는 패러디형 풀스택 실습 프로젝트다.
11. AgentClinic의 초기 헌법은 mission.md와 tech-stack.md와 roadmap.md 세 파일로 구성된다.
12. Hello Hono 기능은 버전 고정과 strict TypeScript와 수동 curl 검증을 명세에 반영하며 시작한다.
13. 사람은 구현 세부보다 기능의 요구사항과 구조와 명세 일치 여부를 중심으로 고수준 리뷰를 수행한다.
14. 작은 커밋과 관리 가능한 변경량은 인지 부채와 대량 코드 검토에서 생기는 AI fatigue를 낮춘다.
15. 테스트와 디버거와 서브에이전트 리뷰는 에이전트의 자체 검증을 넘어서는 이해와 품질 검사를 제공한다.
16. MVP를 한 번에 구현하는 실험은 헌법과 기능 명세가 의도를 보존하는지 검증하는 방법이다.
17. 레거시 프로젝트는 코드와 README와 TODO에서 헌법과 로드맵을 역설계해 SDD 기반으로 전환할 수 있다.
18. 반복 프롬프트와 변경 로그와 검증 절차는 Agent Skills로 패키징해 프로젝트와 조직 전반에서 재사용할 수 있다.
19. Spec Kit과 OpenSpec은 constitution과 plan과 implement와 archive를 포함한 표준화된 SDD 선택지다.
20. 에이전트 중립적인 명세와 MCP와 AGENTS.md와 Skills와 ACP는 도구가 바뀌어도 프로젝트 기억을 보존한다.