승인을 정리해도, 에이전트는 딴길로 샌다

kiro.dev/blog/introducing-kiro

공식 발표문 화면 캡처 · 2025-07-14

Kiro 발표문의 첫 화면. 프롬프트만 반복해 앱을 만들 때 생기는 문제를 짚는 글.

“You guided the agent throughout, but those decisions aren’t documented.”“에이전트를 계속 이끌었지만, 그 결정들은 어디에도 기록되어 있지 않다.”Kiro 발표문 · 2025-07-14

• 프롬프트를 반복하면 일단 동작하는 앱은 나온다
• 그러나 모델이 세운 가정과 결정은 어디에도 남지 않는다
• 요구사항이 흐리면 맞게 만들었는지 판정할 수도 없다

→ 오늘: 먼저 쓰게 한다, 그리고 오래 가게 한다

Plan 모드와 SDD는 같은 시기에 같은 문제를 푼다

도구 안의 Plan 모드와 문서 중심의 SDD(Spec-Driven Development, 스펙 주도 개발)는 서로 대립하지 않습니다. 둘 다 실행 전에 계획을 고정합니다. → 오늘 둘 다 봅니다

SDD는 새 말이 아니다: 1987년 ‘설계 기술서’에서 2025년 ‘스펙 주도 개발’로

같은 약어, 다른 말. Software Design Description(IEEE(Institute of Electrical and Electronics Engineers, 전기전자공학자협회) 1016, 1987)은 사람에게 설계를 전하는 문서, Spec-Driven Development는 스펙으로 개발을 이끄는 방식이다.

설계도를 먼저 그린다는 목적은 같다. 바뀐 것은 읽는 쪽과 스펙의 위상이다

가까운 조상은 옛 설계 문서보다 TDD(Test-Driven Development, 테스트 주도 개발)·BDD(Behavior-Driven Development, 행동 주도 개발)다. 스펙을 먼저 묶고, 기계가 그 스펙으로 확인한다.

SDD(스펙 주도 개발, Spec-Driven Development): 코드보다 스펙을 먼저 쓴다

martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

기술 블로그 화면 캡처 · 2025-10-15

Fowler 사이트에 실린 Böckeler의 글 첫머리와 ‘Definition(정의)’ 절. GitHub·Tessl의 설명도 인용한다.

“The spec becomes the source of truth for the human and the AI.”“스펙이 사람과 AI 모두에게 기준 문서(source of truth)가 된다.”Böckeler · 2025-10-15

스펙을 먼저 쓰는 documentation first를 세 수준(spec-first·anchored·as-source)으로 나눠 도구 비교의 기준을 준다.

글쓴이도 정의가 아직 유동적이라 한다. 스펙을 ‘자세한 프롬프트’로 쓰는 사람도 있다.

오늘 SDD 이야기의 기준 글. 이 글의 세 수준으로 Kiro·Spec Kit을 가늠한다.

SDD는 스펙을 얼마나 오래 쓰느냐로 세 수준이 나뉜다

같은 SDD라도 스펙의 수명이 다릅니다. 글쓴이는 Kiro와 Spec Kit이 대체로 spec-first라고 평가했습니다.

Kiro는 요구사항, 설계, 작업 파일 세 개를 차례로 만든다

kiro.dev/docs/specs

공식 문서 화면 캡처 · 2026-10-28 확인

Kiro 문서 ‘What are specs?’ 화면. 스펙의 종류(Feature·Bugfix·Quick)별로 IDE(Integrated Development Environment, 통합 개발 환경)·CLI(Command-Line Interface, 명령줄 인터페이스)·웹 지원 여부를 표로 보여 준다.

1. requirements.md: 사용자 스토리(사용자 입장의 요구)와 수용 기준(완료 조건). 버그는 bugfix.md로 시작
2. design.md: 구조, 시퀀스, 오류 처리, 테스트 전략
3. tasks.md: 하나씩 추적하는 Task 목록

Kiro는 요구사항을 “WHEN…SHALL…” 문장 틀(EARS)로 쓴다

kiro.dev/docs/specs/feature-specs

공식 문서 화면 캡처 · 2026-10-28 확인

Kiro Feature Specs 문서 첫머리. 새 기능을 단계별로 안내하는 방식이라 소개하고, 주요 장점(구조화된 접근·유연성)을 든다.

.kiro/specs/<이름>/ ├─ requirements.md ├─ design.md └─ tasks.md # requirements.md (EARS = Easy Approach to Requirements Syntax, 요구사항 문장 형식, 문서 예시) WHEN a user submits valid registration data THE SYSTEM SHALL create a new user account → 올바른 가입 정보를 제출하면, 시스템은 새 계정을 만든다

Spec Kit은 슬래시 명령으로 스펙에서 구현까지 단계를 밟는다

github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit

GitHub Blog 화면 캡처 · 2025-09-02

GitHub이 낸 Spec Kit 발표 글. 스펙을 먼저 쓰고 AI로 개발하는 오픈소스 도구 모음 소개.

# 다섯 단계 슬래시 명령 (설치는 각자) /speckit-constitution 원칙 (한 번) /speckit-specify 무엇을·왜 /speckit-plan 기술 선택 /speckit-tasks Task 목록 /speckit-implement 구현

Spec Kit은 기능마다 spec.md와 tasks.md 뼈대를 채운다

github.com/github/spec-kit/blob/main/templates/spec-template.md

저장소 템플릿 화면 캡처 · spec.md의 뼈대

spec.md 템플릿의 맨 위. ‘Feature Specification: [기능 이름]’ 제목과 기능 브랜치·작성일 칸이 보인다.

github.com/github/spec-kit/blob/main/templates/tasks-template.md

저장소 템플릿 화면 캡처 · tasks.md의 뼈대

tasks.md 템플릿의 맨 위. ‘Tasks: [기능 이름]’ 제목과 “기능 구현용 Task 목록 템플릿”이라는 설명.

기능마다 specs/001-이름/ 폴더가 생기고 spec.md · plan.md · tasks.md 등이 들어갑니다. 기능마다 브랜치도 새로 만듭니다.

constitution: 모든 변경에 적용하는 프로젝트 원칙

github.com/github/spec-kit/blob/main/templates/constitution-template.md

저장소 템플릿 화면 캡처

Spec Kit의 constitution 템플릿. ‘[프로젝트 이름] Constitution’ 아래 핵심 원칙 이름·설명을 채우는 빈칸 양식.

프로젝트에 한 번 써 두면 모든 변경에 적용된다. 기능마다 쓰는 spec·plan·tasks와 층이 다르다.

에이전트가 원칙을 과하게 적용하기도 한다(Böckeler 관찰).

CLAUDE.md·AGENTS.md와 같은 층. 결정의 이유를 남긴다는 점에서 ADR(Architecture Decision Record, 아키텍처 결정 기록)과 이어진다.

→ 14교시: ADR로 이어지는 생각

두 도구의 파일 흐름은 거의 같다

이름만 다릅니다. 무엇을 → 어떻게 → 할 일 세 층을 파일로 남기고, 마지막 tasks.md를 하나씩 소화합니다.

SDD가 항상 답은 아니다

martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

기술 블로그 화면 캡처 · 2025-10-15

Böckeler 글의 첫머리(제목: Kiro·spec-kit·Tessl 이해하기). 이 글의 관찰 부분에 아래 한계 지적이 있다.

“I’d rather review code than all these markdown files.”“이 마크다운 파일들을 전부 보느니 차라리 코드를 리뷰하겠다.”Böckeler · 2025-10-15

• Kiro: 작은 버그 하나가 사용자 스토리 4개, 수용 기준 16개로 부푼다
• 스펙을 써 줘도 에이전트가 지시를 무시할 때가 있다
• 크기에 맞는 흐름을 고르는 것은 사람 몫

→ 결론: 작은 일엔 스펙을 작게, 큰 일에만 풀 세트

Plan 모드: 읽고, 계획하고, 승인받고, 편집한다

승인 전에는 소스를 수정하지 않습니다. 계획이 마음에 들지 않으면 “계속 계획”으로 되돌립니다.

Plan 모드는 승인 전에 소스를 안 고치고, 계획은 직접 고친다

code.claude.com/docs/en/permission-modes

공식 문서 화면 캡처 · 진입

Plan 모드 설명. 파일을 읽고 조사해 계획만 제안하며 소스는 고치지 않는다. 계획 중 셸 명령 처리 조건도 적혀 있다.

code.claude.com/docs/en/permission-modes

공식 문서 화면 캡처 · 승인

계획 승인 선택지. 자동 모드로 승인, 편집마다 확인, 계속 계획 중에서 고른다.

Cursor도 계획을 파일로 남기고, 사람이 고친 뒤 실행한다

cursor.com/blog/plan-mode

공식 블로그 화면 캡처 · 2025-10-07

Cursor의 Plan Mode 발표문. 코드베이스를 조사해 계획 파일(.plan.md)을 만든다.

코드베이스를 조사해 계획 파일(.plan.md)과 체크 가능한 todo를 만든다. 사람이 고친 뒤 Build로 실행한다.

계획 한 파일이라 Kiro·Spec Kit처럼 스펙·설계를 층으로 나누지는 않는다.

Claude Code Plan 모드, Kiro의 tasks.md와 같다. 계획을 대화가 아닌 파일로 남기는 습관.

제가 쓰는 방식: 이슈 하나가 열두 단계를 지난다

스펙 · 계획 · 구현 세 곳에서 리뷰하고, 블로커가 없을 때만 다음으로 넘어갑니다. 직접 도식 · 강사 실제 화면으로 교체 예정

세 번의 리뷰: 대상이 다르면 질문도 다르다

같은 문서 전체를 매번 다시 쓰지 않습니다. 비차단 개선은 후속 이슈로 넘기고, 블로커가 남으면 자동으로 통과시키지 않습니다.

스펙을 써도, 일이 길어지면 창이 찬다

code.claude.com/docs/en/context-window

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 문서의 컨텍스트 창 설명. 지침·읽은 파일·응답·도구 결과가 한 창에 쌓이는 모습.

• 컨텍스트 창(AI가 한 번에 볼 수 있는 분량)에 지침, 읽은 파일, 응답, 도구 결과가 모두 쌓인다
• 가득 차면 대화를 요약해 이어 간다 (자동 압축)
• 2025-03-18부터 “무한 대화 길이”를 내세워 기본 제공

→ 다음 장: 요약 뒤에 무엇이 남나

압축 뒤: 디스크의 파일은 남고, 대화는 요약된다

code.claude.com/docs/en/context-window

공식 문서 화면 캡처 · 2026-10-28 확인

컨텍스트 창 문서의 시뮬레이션 화면. 시스템·CLAUDE.md·메모리·스킬·MCP(Model Context Protocol, 모델 컨텍스트 프로토콜) 등이 한 창에 차례로 쌓이는 모습.

• 다시 주입: CLAUDE.md, Plan 모드 계획 (디스크에서)
• 일부만: 읽은 파일은 최근 수정한 5개까지만 다시 읽음
• 요약에 든 만큼만: 그 밖의 대화는 요약으로 대체

입력이 길어질수록 성능이 흔들린다: Context Rot

trychroma.com/research/context-rot

기술 보고서 화면 캡처 · 2025-07-14

Chroma의 Context Rot 보고서 첫 화면. 입력 길이에 따라 모델 성능이 어떻게 변하는지 평가한 글.

18개

평가한 LLM(Large Language Model, 대규모 언어 모델) 18개에서
입력이 길수록 성능이 불안정해졌다

Chroma Technical Report, 2025-07-14
GPT-4.1 · Claude 4 · Gemini 2.5 · Qwen3 포함

압축 대비: 진행 파일에 적어 둔다

anthropic.com/engineering/effective-harnesses-for-long-running-agents

공식 엔지니어링 블로그 화면 캡처 · 2025-11-26

Anthropic 엔지니어링 글 본문. 압축만으로는 지시가 완벽히 넘어가지 않는 문제와, 첫 세션이 init.sh·진행 파일을 만드는 두 단계 해법.

# Anthropic 글의 인계 장치 claude-progress.txt 한 일의 기록 feature list (JSON) 기능 목록 처음엔 모두 passes: false init.sh 개발 서버 실행 git commit 세션마다 커밋 ✓ 세션당 기능 하나, 끝에 기록

세션 경계를 넘는 것은 파일뿐이다

스펙, 계획, 진행 기록을 파일에 남기면, 압축이나 새 세션 뒤에도 같은 기준에서 다시 시작합니다.

스펙이 붙잡고, 파일이 남는다

스펙과 Task 목록은 딴길을, 파일은 압축을 막습니다. 다음 시간에는 스펙을 실패하는 테스트로 바꿉니다. → 6교시 TDD와 DDD

스펙이 있어도 “다 했다”는 말은 검증되지 않는다

github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit

GitHub Blog 화면 캡처 · 5교시에서 본 화면

5교시에서 본 GitHub의 Spec Kit 발표 글 제목 화면. “AI로 스펙 주도 개발: 새 오픈소스 툴킷으로 시작하기”.

• 스펙과 Task 목록이 에이전트가 딴길로 새는 것을 줄인다
• 하지만 “다 했다”는 말은 에이전트의 말일 뿐
• 코드가 커지면 한 번에 건드리는 범위도 넓어진다

스펙, 테스트, 경계가 서로 다른 실패를 막는다

세 겹은 서로 다른 실패를 막습니다. 스펙은 SDD(Spec-Driven Development, 스펙 주도 개발), 테스트는 TDD(Test-Driven Development, 테스트 주도 개발), 경계는 DDD(Domain-Driven Design, 도메인 주도 설계)입니다. 오늘은 가운데 테스트부터 봅니다. → 5교시 SDD, 이어서 TDD

TDD: 실패하는 테스트를 먼저 쓴다

martinfowler.com/bliki/TestDrivenDevelopment.html

Martin Fowler bliki 화면 캡처 · 2026-10-28 확인

Fowler의 TDD 설명 글. 테스트 목록에서 하나 골라 쓰고(Red) → 통과시키고(Green) → 정리(Refactor)하는 반복 도식.

1. 다음 기능의 테스트를 쓴다 (Red: 아직 실패)
2. 통과할 때까지 구현한다 (Green: 통과)
3. 동작은 그대로 두고 구조를 정리한다 (Refactor)

Kent Beck이 1990년대 후반 익스트림 프로그래밍의 일부로 발전시킨 기법

사람이 분량 때문에 건너뛰던 TDD를 AI에게

code.claude.com/docs/en/best-practices

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 모범 사례 문서의 ‘Instead of(이렇게 말하지 말고) / Try(이렇게)’ 표. “로그인 버그 고쳐” 대신 실패 재현 테스트를 쓰게 한다.

• 사람: 테스트 쓰는 시간이 구현만큼 들어 생략
• AI: 테스트 수십 개를 쓰는 비용이 거의 없다
• 공식 문서의 프롬프트 예: “write a failing test that reproduces it, then fix it” (재현하는 실패 테스트를 쓰고, 그다음 고쳐라)

완료는 에이전트의 말이 아니라 통과 결과

code.claude.com/docs/en/best-practices

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 문서의 ‘실행해서 확인할 수단을 주라’는 절. 통과·실패를 돌려주는 검증 수단 예시.

“Give Claude something it can run that comes back pass or fail.”“Claude에게 실행했을 때 통과나 실패를 돌려주는 무언가를 주어라.”Claude Code Docs · Best practices

• 검증 수단: 테스트 파일, 빌드 종료 코드, 린터(코드 규칙 검사기)
• repo의 CLAUDE.md에 테스트 실행 명령을 적는다
• “All tests pass(모두 통과)”만 믿지 말고 실행 출력을 요구

Red 확인이 먼저, Green은 그다음

규칙: 이미 제출한 지원은 다시 제출할 수 없다. 실패가 규칙을 가리키는지 확인한 뒤에 구현합니다.

에이전트는 테스트만 통과하는 지름길을 찾기도 한다

anthropic.com/news/claude-4

Anthropic 발표문 화면 캡처 · 2026-10-28 확인

Claude 4 발표문에서 모델이 지름길·허점을 쓰는 행동을 줄였다고 밝힌 문단.

지름길·허점을 쓰는 행동이 Sonnet 3.7보다 65% 덜 나온다고 발표했다(지름길에 취약한 에이전트 과제 기준).

줄었을 뿐 사라진 것은 아니다. 수치는 모델을 만든 회사가 직접 발표한 것이다.

모델이 좋아지길 기다리지 않고 구조로 막는다. 다음 장부터 그 대응이 이어진다.

속임수 세 가지: 고치고, 건너뛰고, 박아 넣기

속임수에 대한 대응: 막고, 대조하고, 직접 본다

테스트를 먼저 커밋해 기준을 고정하고, 파일을 보호하고, 다른 눈으로 검토합니다. 마지막 판정은 사람입니다.

권한 deny: 테스트 파일은 수정 금지

code.claude.com/docs/en/permissions

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 권한 문서. allow·ask·deny 규칙의 뜻과, deny가 먼저 평가되는 순서를 설명한다.

// .claude/settings.json { "permissions": { "deny": [ "Edit(tests/**)" ] } }

훅: 수정 시도를 막고 이유를 돌려준다

code.claude.com/docs/en/hooks-guide

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 훅 가이드의 ‘보호 파일 수정 차단’ 예제. 훅(도구 실행 직전에 끼우는 스크립트)으로 수정을 막는 방법.

# 도구 실행 직전(PreToolUse)에 돌린 실제 결과 $ echo '{"tool_input":{"file_path": "/app/transition_test.py"}}' | protect-tests.sh Blocked: ... protected test file. Fix the implementation instead. exit=2 ← 차단, 메시지는 에이전트에게 $ ... "/app/transition.py" ... exit=0 ← 통과

리뷰어 서브에이전트: 스펙과 테스트를 대조한다

code.claude.com/docs/en/sub-agents

공식 문서 화면 캡처 · 1교시와 같은 화면

Claude Code 서브에이전트 문서(‘Create custom subagents’). 서브에이전트(자기 컨텍스트·권한을 가진 보조 에이전트)를 만드는 법.

구현 세션과 별도 컨텍스트에서 diff만 보므로 자기 코드를 너그럽게 보는 편향이 없다.

찾으라고 하면 항상 무언가를 찾아 불필요한 추상화·테스트가 늘 수 있다. 스타일 지적은 빼라고 적는다.

deny·훅이 막는 방어라면 리뷰어는 스펙과 대조하는 방어. 질문은 좁게 고정한다.

→ 7교시

DDD: 업무 영역의 규칙을 코드 안의 모델로

martinfowler.com/bliki/DomainDrivenDesign.html

Martin Fowler bliki 화면 캡처 · 2026-10-28 확인

Fowler의 DDD(도메인 주도 설계) 설명 첫 화면. 복잡한 업무 규칙을 모델로 만들어 코드에 둔다.

복잡한 업무 규칙을 모델로 만들어 코드에 둔다(2003년 Eric Evans의 책에서 유래).

단순한 앱에는 과하다. 전부 다루려면 책 한 권 분량이다.

앱 복잡도에 맞춰 필요한 만큼만 쓴다. 뒤의 PoC(Proof of Concept, 개념 증명)·엔터프라이즈 구분의 근거.

→ 결론: 앱 복잡도에 맞춰 필요한 만큼만 쓴다

유비쿼터스 언어: 사람과 코드가 같은 단어를 쓴다

martinfowler.com/bliki/UbiquitousLanguage.html

Martin Fowler bliki 화면 캡처 · 2026-10-28 확인

Fowler의 ‘유비쿼터스 언어’ 설명. 개발자와 사용자가 같은 엄밀한 말을 쓴다는 개념.

• 개발자와 사용자가 쓰는 엄밀한 공통 언어
• 소프트웨어는 모호함을 잘 다루지 못한다
• 에이전트용: 용어집을 스펙·CLAUDE.md에 적고, 코드 이름도 그 단어로

바운디드 컨텍스트: 같은 단어, 영역마다 다른 뜻

martinfowler.com/bliki/BoundedContext.html

Martin Fowler bliki 화면 캡처 · 2026-10-28 확인

Fowler의 Bounded Context 글. 영업·지원 영역이 Customer(고객)·Product(상품)를 각자 다르게 모델링하는 도식.

큰 모델 하나 대신 컨텍스트별 모델로 나눠, Customer·Product처럼 같은 단어의 뜻 충돌을 피한다.

컨텍스트 사이 관계를 명시적 계약으로 정해야 한다. 폴더만 나눈다고 경계가 되지는 않는다.

이 구조가 다음 장에서 에이전트의 작업 범위가 된다.

예: 공고 · 지원 기록 · 알림, ‘상태’는 셋이 다르다

각 영역이 데이터와 규칙을 소유하고, 다른 영역과는 조회 계약·이벤트로만 만납니다. 실제 앱이 이 구조로 구현되어 있다는 뜻이 아닌 설계 예시입니다.

왜 에이전트에게 경계가 필요한가: 볼 범위 축소

경계는 컨텍스트 창 절약, 수정 범위 제한, 영역별 테스트 실행을 한꺼번에 줍니다.

클린 아키텍처: 의존은 안쪽으로만

blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html

Uncle Bob 블로그 화면 캡처 · 2026-10-28 확인

Uncle Bob의 클린 아키텍처 글 중 의존성 규칙 문단. 안쪽 원은 바깥쪽을 알아서는 안 된다.

“source code dependencies can only point inwards.”“소스 코드의 의존은 안쪽으로만 향할 수 있다.”Robert C. Martin · 2012

의존 방향이 안쪽 하나라 규칙이 단순하다. 안쪽은 엔티티(업무 규칙), 바깥은 UI(User Interface, 사용자 화면)·DB(Database, 데이터베이스)·프레임워크.

작은 PoC에 쓰면 계층·추상화가 과잉 개발로 흐른다.

엔터프라이즈 규모일 때만 프롬프트에 적는다. 규모를 한 줄로 밝히는 것이 핵심.

프롬프트에 수준을 적는다: PoC냐, 엔터프라이즈냐

같은 요구사항도 규모를 적지 않으면 에이전트가 임의로 정합니다. 한 줄이면 충분합니다.

같은 기능도 PoC냐 클린 아키텍처냐에 따라 모양이 달라진다

현장에서 같은 요구사항을 두 프롬프트로 시켜 파일 수와 줄 수를 직접 세어 비교합니다.

오늘 본 것: 세 겹으로 범위를 묶는다

테스트는 먼저 쓰고, 먼저 커밋하고, 못 고치게 합니다. 경계는 작게, 수준은 프롬프트에 한 줄로. → 7교시 서브에이전트와 워크트리

압축만으로는 창이 모자라서, 일을 나눠 맡기게 됐다

research.trychroma.com/context-rot

Chroma 기술 보고서 화면 캡처 · 5교시에서 본 자료

Chroma의 기술 보고서(2025-07-14). 입력이 길어질수록 LLM(Large Language Model, 대규모 언어 모델) 성능이 고르지 않게 떨어진다는 것을 모델 18개로 확인했다.

• 스펙·테스트를 갖춰도 탐색과 로그가 창(한 번에 읽는 입력 범위)을 채운다
• 압축하면 결정의 이유가 사라진다
• 해법 ①: 일을 맡겨 창을 나눈다
• 해법 ②: 일을 맡겨 폴더를 나눈다

← 5교시 · 6교시

서브에이전트는 자기 창에서 일하고 요약만 돌려준다

code.claude.com/docs/en/sub-agents

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 공식 문서 ‘커스텀 서브에이전트 만들기’ 첫 화면. 검색 결과·로그가 메인 대화를 채우지 않게 별도 에이전트에 맡기는 기능이라고 설명.

“the subagent does that work in its own context and returns only the summary.”서브에이전트가 그 일을 자기 컨텍스트에서 처리하고, 요약만 돌려준다.Claude Code Docs · Create custom subagents

검색·로그가 자기 창에서 처리돼 메인 대화가 깨끗하다. 시스템 프롬프트·도구·권한도 따로 준다.

대화 이력과 읽은 파일을 보지 못한다. 요청도 보내므로 사용량은 메인과 같은 한도에서 차감된다.

압축이 쌓인 맥락을 줄인다면, 이쪽은 애초에 쌓이지 않게 한다. 7교시의 첫 번째 장치.

탐색은 다른 창에서, 메인에는 결론만

서브에이전트는 대화 이력을 보지 못합니다. 메인이 작업 내용을 요약해 건네고, 서브에이전트는 거기서 시작합니다.

기본 제공 서브에이전트 셋: 읽기 전용 둘, 만능 하나

서브에이전트는 마크다운 파일 한 장으로 정의한다

필드 몇 개로 정의하고, 같은 이름이면 위쪽 위치가 이긴다

code.claude.com/docs/en/sub-agents

공식 문서 표 캡처 · 같은 이름이면 위쪽이 이깁니다

서브에이전트 정의 파일을 둘 수 있는 위치 표. 관리 설정, 실행 옵션, 프로젝트, 내 홈, 플러그인 순으로 숫자가 작을수록 우선.

필드	역할
disallowedTools	쓰지 못할 도구
permissionMode	권한 모드(승인 방식)
maxTurns	최대 턴 수(주고받는 횟수)
background	항상 백그라운드
isolation	worktree로 격리(별도 폴더)

서브에이전트는 자동 위임·말로·@-멘션·--agent로 부른다

서브에이전트가 일하는 동안 메인은 다른 일을 할 수 있습니다(백그라운드). → 8교시

독립된 조사는 동시에 시킨다

공식 예시: “Research the authentication, database, and API modules in parallel using separate subagents”(인증·DB(Database, 데이터베이스)·API(Application Programming Interface, 응용 프로그램 인터페이스) 모듈을 서브에이전트 따로 병렬로 조사해 줘). 조사 경로가 서로 독립일 때 잘 맞습니다.

탐색·로그·리뷰는 맡기고, 되묻는 일은 메인에서

서브에이전트는 맥락을 아끼지만 사용량은 줄이지 않는다

기본값은 동시 20개, 중첩 3단계. → 결론: 맥락은 아끼지만 비용은 늘고, 결과가 길면 메인 창도 다시 찹니다.

한 폴더에서 에이전트 둘이 일하면 서로 덮어쓴다

해법은 작업마다 폴더와 브랜치(코드 갈래)를 따로 주는 것입니다. 로그인·검색 같은 작업을 동시에 시킬 때 필요합니다.

git worktree로 한 저장소에서 브랜치마다 작업 폴더를 갖는다

git-scm.com/docs/git-worktree

git 공식 문서 화면 캡처

git 공식 문서의 git-worktree 설명. 한 저장소에 작업 폴더를 여럿 붙여 브랜치 여러 개를 한 번에 체크아웃(펼치기)할 수 있다.

$ git worktree add ../app-login -b feat/login $ git worktree add ../app-search -b feat/search $ git worktree list /home/me/app a1b2c3d [main] /home/me/app-login a1b2c3d [feat/login] /home/me/app-search a1b2c3d [feat/search] $ git worktree remove ../app-login ✓ “check out more than one branch at a time” = 브랜치 여럿을 한 번에 펼친다 ! 같은 브랜치는 두 곳에 못 연다(기본값)

저장소 기록은 하나, 작업 파일은 각자

커밋과 브랜치는 모든 워크트리에 즉시 보입니다. 파일, HEAD(현재 커밋 표시), 인덱스(커밋 대기 목록)는 워크트리마다 따로입니다.

Cursor는 2025년 5월 백그라운드 에이전트로 병렬 실행을 내놓았다

cursor.com/changelog/0-50

공식 변경 기록 화면 캡처 · 2025-05-15

Cursor 0.50 업데이트 소개 글. 요금제 단순화와 함께 병렬 작업용 Background Agent(백그라운드 에이전트)를 처음 내놓았다.

“Background Agent for parallel task execution.”병렬 작업 실행을 위한 백그라운드 에이전트.Cursor Changelog 0.50 · 2025-05-15

에이전트가 편집기와 별개로 돌아, 여러 작업을 동시에 맡길 수 있다.

초기 프리뷰로 점진 배포. 이 글에는 격리 방식의 세부가 없어 확인할 수 없다.

병렬 실행을 제품 기능으로 먼저 내놓은 사례. 동시 실행이 기본 기능이 되어 가는 출발점.

Claude Code는 --worktree 한 줄로 격리된 세션을 연다

code.claude.com/docs/en/worktrees

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 공식 문서 ‘워크트리로 병렬 세션 실행’. 워크트리는 파일·브랜치는 따로, 저장소 기록은 공유하는 작업 폴더라고 설명.

# CHANGELOG 2.1.49 Added --worktree (-w) flag to start Claude in an isolated git worktree # = 격리된 워크트리에서 Claude를 시작하는 옵션 추가 $ claude --worktree feature-auth $ claude -w feature-search # 다른 터미널에서 ✓ .claude/worktrees/<이름>/ ✓ 브랜치 worktree-<이름> ✓ 나갈 때 변경을 확인하고 유지·삭제를 묻는다 ! .env 같은 파일은 .worktreeinclude(복사 목록)로 복사

Codex 앱은 워크트리를 기본 기능으로 넣었다

developers.openai.com/codex/app/worktrees

공식 문서 화면 캡처 · 2026-10-28 확인

OpenAI Codex 앱의 Worktrees 문서. 워크트리를 저장소의 두 번째 복사본으로 정의하고 Local·Worktree·Handoff 용어를 풀이.

같은 프로젝트의 여러 채팅이 서로 방해 없이 돈다. Local(원래 폴더)↔Worktree(복사본)를 Handoff(넘기기)로 오간다.

Git 저장소에서만 동작한다. 출시일은 2월 초까지만 확인했다.

Claude Code · Cursor · Codex가 같은 방향으로 모였다. 특정 도구만 정답이 아니다.

둘을 합치면 서브에이전트마다 자기 워크트리를 갖는다

합칠 때 충돌: 격리는 충돌을 미룰 뿐

워크트리는 작업 중의 덮어쓰기를 막을 뿐, 합칠 때의 충돌은 막지 못합니다. 변경 범위를 미리 나누는 것이 가장 싼 해법입니다.

이어 붙이면 한 흐름: 계획에서 합치기까지

계획은 스펙과 Task(5교시), 완료 기준은 테스트(6교시), 리뷰어는 읽기 전용 서브에이전트, 구현은 워크트리 안의 워커입니다. → 8교시 실습

병렬 방법은 여럿이고, 서브에이전트·워크트리·/batch는 역할이 다르다

code.claude.com/docs/en/agents

공식 문서 화면 캡처 · 2026-10-28 확인

Claude Code 공식 문서 ‘에이전트 병렬 실행’의 비교 표. 서브에이전트 등 5가지 방식이 각각 언제 맞는지를 나란히 설명.

방법	장점	한계
서브에이전트	한 세션 안에서 맡기고 맥락을 나눈다	사용량 ×N, 이력을 못 본다
워크트리	파일 편집을 격리한다	합칠 때 충돌은 못 막는다
/batch(스킬)	큰 변경 하나를 서브에이전트 5~30개로 쪼개 각자 워크트리에서 작업	두 방법의 한계를 함께 진다

→ 의미: 워크트리는 돌리는 방법이 아니라 편집 격리 도구, /batch는 둘을 묶은 스킬

→ 13교시 · agent teams

오늘 본 것: 창을 나누고, 폴더를 나누고, 다음은 ‘얼마나 오래’

서브에이전트는 맥락을, 워크트리는 파일을 나눕니다. → 8교시 실습 2 · 과제 2

제 방식: 스펙 개요 → Task → 이슈를 만들고, 이슈 하나를 리뷰까지 끝낸다

제가 보는 것은 내가 한 답 · 결정 한 줄 요약 · 스모크 결과 셋입니다. 각 리뷰는 블로커가 없으면 종료, 예산이 다 되면 중단하고 진행 파일에 인계합니다. PR(Pull Request, 병합 요청)·CI(Continuous Integration, 지속적 통합)·머지(9–12)는 16교시입니다.

첫 프롬프트(예): 질문을 먼저, 구현은 승인 뒤에

> 내 하네스에 딴길 방지 장치를 더하고 싶다. 어떤 게 필요한지부터 같이 정하자. 아직 코드는 쓰지 마. 운영 기준 순서로 가자. 8 Spec 개요 → 13 Task 분할 → 14 GitHub 이슈 등록. 질문은 한 번에 하나씩, 네 추천 답과 이유를 같이, 8개 안에서 끝내. 각 이슈마다 어겨 보는 스모크 시나리오를 하나씩 붙여. 끝나면 docs/spec.md, TASKS.md, 이슈 초안을 만들고 내가 “승인”할 때까지 기다려. 승인하면 이슈 하나를 골라 이슈별 워크플로우 1~8로: 분석 → ADR 점검 → 이슈 스펙 → 스펙 리뷰 → 구현 계획 → 계획 리뷰 → 구현(테스트 먼저) → 구현 리뷰. 리뷰는 블로커가 없으면 끝내고, 예산이 다 되면 멈춰서 progress.md에 인계해.

github.blog · Spec Kit

SDD(Spec-Driven Development, 스펙 주도 개발) 도구의 예 · 2025-09-02

GitHub의 Spec Kit. 스펙 → 계획 → Task 순서로 에이전트를 이끄는 오픈소스 도구 모음. 우리는 문서 몇 장으로 같은 순서를 밟는다. 프롬프트의 ADR(Architecture Decision Record, 아키텍처 결정 기록)은 결정과 이유를 남긴 문서.

에이전트가 물어야 할 질문은 단계마다 하나씩이다

8·13단계의 결정은 한 줄씩이다: 번호 붙은 요구와, 끝 조건이 있는 Task (예)

14단계: 장치마다 이슈 한 건을 만든다 (#1~#4는 메뉴의 예)

이슈 본문: 종류 · 상위(spec) · 기대 산출물 · 범위 밖 · 수용 조건 · 상태. 내게 필요한 것을 골라 처리하고 나머지는 이슈로 남깁니다. → 12교시: 이 이슈를 스킬로

구현에 들어가기 전에 저는 다섯 가지만 확인한다

1–6단계는 문서로 수렴시킨다: 분석, ADR 점검, 스펙, 계획 그리고 두 번의 리뷰

7단계: 테스트를 먼저 쓰고 실패를 보여 달라고 한 뒤, 막는 장치를 만들게 한다

구현은 테스트가 막고, 구현 리뷰는 별도의 리뷰어에게 맡긴다

리뷰 지적이 나와도 테스트는 건드리지 않고 구현만 고치게 합니다. 보호 장치가 지켜 줍니다.

예산이 다 되면 통과시키지 않고, 진행 파일에 적고 멈추게 한다

code.claude.com/docs/en/hooks-guide

공식 문서 화면 캡처 · 2026-10-28 확인

훅 가이드의 ‘압축 뒤 맥락 다시 넣기’ 예. 압축 직후 파일을 다시 읽어 맥락에 넣는 방식을 이 문서가 설명한다.

> Task 하나를 끝낼 때마다 progress.md를 갱신해. 지금 상태 · 결정 · 버린 것 · 블로커 · 다음 한 걸음. 압축된 직후에는 이 파일이 자동으로 다시 읽히게 해. 블로커가 남은 채 예산이 떨어지면 통과시키지 말고 멈춰서 여기에 인계해. # 스모크 (예시) > /compact > 지금 어디까지 했어? ✓ 이슈 #2, 8단계 리뷰 중 · 훅 채택(ADR-0002) ✓ 버린 것: 전체 tests 금지(새 테스트도 막힘) ✓ 다음: 이슈 #1

스모크: 이슈의 수용 조건을 일부러 어겨 보고, 막힌 것까지 기록한다

이슈 번호·단계, 블로커와 반복 횟수, 남은 이슈와 다음 한 걸음도 한 줄씩 함께 적습니다. 화면이나 로그를 하나씩 남깁니다.

다음 회차까지 해 볼 것: 장치 하나를 골라 더하고, 어겨 보며 확인한다

완성도보다 해 보며 알게 된 것을 나눕니다. 코드나 저장소를 보여 주지 않아도 됩니다. → 12교시: 이 워크플로우를 스킬로

막힐 때: 대부분은 하네스에게 주는 지시를 고치면 풀린다