인트로

배경 — 병목은 사람의 시간

• 본업(게임회사) 병행 1인 사이드 프로젝트 — Unity 6, 2D 턴제 전술 RPG
• 회사에서는 추구하지 못하는 에이전틱 프로젝트를 경험하기 위한 삽질들 — 이 발표는 그 기록
• 코딩 시간 자체가 희소 자원. 하루에 낼 수 있는 시간이 들쭉날쭉
• AI 보조 개발의 흔한 실패 패턴:
  • 같은 실수를 매 세션 반복 (컨텍스트가 휘발)
  • 시킨 것만 하거나, 안 시킨 것까지 함 (범위 통제 실패)
  • "됐다"고 하는데 실제로 안 됨 (검증 부재)

이 발표의 프레임:

AI에게 일을 "시키는" 게 아니라, AI가 일할 수 있는 시스템을 만든다

인트로

전체 파이프라인 — 오늘의 지도

• 앞으로 각 챕터가 이 그림의 한 구간을 확대합니다
• 1막: 파이프라인 따라가기 (①~⑥)
• 2막: 무인화 (⑦)
• 3막: 이게 왜 굴러가고, 어떻게 유지되는가

1막 · 파이프라인 ①

이슈 인프라 — 기계가 읽을 수 있는 TODO

• GitHub issue = 단일 TODO 트래커 — 지금 손댈 버그부터 마일스톤급 스펙, 리뷰 발 제안까지 전부
• 라벨은 area:* 하나 + type:* 하나 (우선순위 라벨 없음) — 정리된 라벨 = 기계도 이슈를 집는다 (→ 2막)
• 워크트리 2개 병렬 운용 — epoch(신규 개발) / epoch-issues(버그·부채) → AI 세션 2개 동시 가동

1막 · 파이프라인 ②

/solve — 진입 라우터

문제는 있는데 어디서부터 시작할지 모를 때, 30초 triage로 사고 스킬에 라우팅

• 포인트: "어떤 스킬을 쓸지 고민하는 비용" 자체를 제거 — 스킬 30개+에서 라우터 없으면 사람이 병목

1막 · 파이프라인 ②

라우팅 대상 사고 스킬 4종 — 기원과 차이

한 줄 구분: first-principles는 "접근 자체"를 부수고, why는 "존재 이유"를 캐고,
brainstorming은 "정해진 것"을 설계로 다듬고, autoloop는 "되는 것"을 수치로 조인다

1막 · 파이프라인 ③-1

SPEC — 4가지를 못 채우면 시작하지 않는다

/plan-spec: 구현 전에 4필수 명세를 대화형으로 수집·검증

• 산출물: vault features/{YYMMDD}-{기능명}/1-SPEC-*.md — repo가 아니라 Obsidian에
• 규모 판정 후 분기: 중대형 → DESIGN 심화 / 소형(4조건 전부 충족 시만) → PLAN 직행
  • 기본값은 DESIGN 경유 (보수적 분기 — 건너뛰기가 예외)

1막 · 파이프라인 ③-2

DESIGN — 결정을 문서로 고정한다

/plan-design: 8단계 설계 심화. 불필요한 단계는 스킵

구현 가능성 → 기술 스택 → 사용 흐름 → 화면 → API → 데이터 → 아키텍처 → 기술 결정

• 여기서 중요하게 보는 것: "결정"을 남기는 것
  • AI 세션은 갈아치워진다. 다음 세션·다른 AI가 와도 결정이 문서에 있으면 흔들리지 않음
  • "왜 A안이 아니라 B안인가"까지 기록 → 나중에 리뷰가 반박해도 재논쟁 안 함
• 산출물: 같은 폴더에 2-DESIGN-*.md

실제 예시 (vault features/ 폴더):

260620-balance-sim-harness/
  ├── 2-DESIGN-balance-sim-harness.md
  ├── 3-PLAN-balance-sim-harness-01-core-stats.md
  └── 3-PLAN-balance-sim-harness-02-...

1막 · 파이프라인 ③-3

PLAN — 실행자의 판단 여지를 없앤다

/writing-plans: 구현 계획 문서. 이 plan은 사람이 아니라 다른 AI(Codex)가 실행

• 파일 단위 책임 분해 → 2~5분짜리 bite-sized 단계 → 코드/명령/예상 결과 완전 명시
• 여기서 중요하게 보는 것: 모호함 = 실행 AI의 창의성 발휘 지점 = 사고 지점
  • "적절히 처리" 같은 문구가 남아 있으면 plan이 아직 안 끝난 것
  • 단계마다 검증 방법(컴파일·테스트·grep)까지 박음

단계가 나뉜 이유가 핵심:

1막 · 파이프라인 ④-1

역할 분담 — 3자 체제

• "코드를 건드리는 일은 전부 Codex" — 규칙에 예외를 안 두는 게 포인트
  • "작은 변경이니까 직접"이 무너지는 순간 역할 분리 전체가 무너짐 (실제로 1회 지적받고 룰로 적립)
• 역할 분리의 부수 효과: 구현자(Codex)와 관리자(Claude)의 컨텍스트가 섞이지 않음
  → 리뷰 독립성의 기반 (⑥에서 계속)

1막 · 파이프라인 ④-2

Codex 4-tier — 모든 작업에 최고 모델을 쓰지 않는다

Tier	모델/강도	용도
A	gpt-5.5 + xhigh	아키텍처, 대규모 리팩토링, 보안 감사, long-horizon 디버깅
B 디폴트	gpt-5.5 + high	일반 구현·수정·plan 기반 작업
C	gpt-5.4 + xhigh	단발성 깊은 분석·알고리즘 (long-horizon 아님)
D	gpt-5.4 + high	코드 리뷰 고정, 탐색·린트·문서·리서치

• 전부 최상위 tier로 박으면: 단가 약 2배 + 지연 큼. 작업 유형이 tier를 결정
• 리뷰가 D인 이유: 리뷰는 넓고 얕게 여러 번 도는 게 깊게 한 번보다 가성비가 좋았음
• 위임 브리핑에 함정 회피 조항을 상시 탑재 (예: "인터페이스/공개 API 추가 금지",
  "Unity 에셋 확인은 unity-cli로" — 전부 과거 사고에서 나온 문구, 3막 복선)

1막 · 파이프라인 ⑤

검증 — AI가 자기 변경을 자기가 검증한다

DoD: 컴파일 → 콘솔 에러 → 모듈별 런타임 1회 (전투=턴 진행, UI=화면 진입/복귀, …룰로 명문화)

• unity-cli-bridge — 외부 CLI가 실행 중인 Editor와 통신: 컴파일·콘솔·테스트·C# 즉석 실행·에셋 조회
• 샌드박스 런처 — 세이브/내비게이션 우회, 전투 씬 직행 스모킹테스트. 사람에게 떠넘기지 않음
• 사람의 몫도 정의 — 완료 보고에 "무엇을 띄워 무엇을 확인하라" 런타임 검증 절차 항상 첨부

❯ 너가 직접 테스트 검증해줘
● 네, 직접 전투까지 구동해서 적 AI 이동을 검증하겠습니다. 먼저 현재 Editor 상태를 봅니다.
  Ran 1 shell command
● PlayMode가 아닙니다(System.unity). PlayMode 진입 후 재연결을 기다립니다.
● Background command "Poll for bridge reconnect after PlayMode" completed (exit code 0)
● 타이틀 화면입니다. 이어하기(LoadButton)로 세이브 슬롯을 확인합니다.
● 슬롯 1은 캠프(출진 준비)입니다. 출진 준비 → 전투 준비 → 배치 → 전투 시작.
● 빈 슬롯 확인 팝업이 떴습니다. Yes로 전투를 시작합니다.
● Running 1 shell command…
  ⎿ $ U=~/.unity-cli-bridge/unity-cli/unity-cli
    P=~/dev/my-game/UnityProject
    "$U" qa click --target "/[BattleUICanvas]/UIYesNoPopup(Clone)/Root/ButtonGroup/YesButton" --project "$P" --json --output compact
✻ Spelunking… (2m 21s · ↓ 6.7k tokens · thinking with xhigh effort)

[09:22:45] [Navigation] Replace (Dispose): TitleScreen
[09:23:02] [Navigation] Push: PrepareHubSortieScreen (Stack: 2)
[09:23:02] [Navigation] Clear (Count: 2)
[09:23:02] Scanned graphs in 27 ms
[09:23:02] [CinemachineCameraController] Confiner setup complete
[09:23:02] [BattleRng] seed=1876936875 (override=False)
[09:23:26] [BattleWeather] WeatherChanged Clear -> Cloudy
[09:23:29] [QADBG] phase=PlayerTurn detect=True selPos=(13, 2)
           P 에리히 pos=(13, 2) hp=100/100

Unity Editor 게임 화면: BattleScene 진입, 플레이어 턴 대기 (캡처 생략)

1막 · 파이프라인 ⑥

리뷰 — 구현 세션 ≠ 리뷰 세션

흐름: 작업 완료 → 로컬 Codex diff 리뷰(P1/P2/P3 + 파일/라인 + 원인 + 권고) → 반영 → ready PR

• 구현 세션 ≠ 리뷰 세션 — 같은 추론 흐름 = 같은 사각지대(confirmation bias). 리뷰는 항상 신규 세션,
  구현 세션이 "리뷰까지 했다"고 하면 무효 처리 — 사람 팀의 "셀프 어프루브 금지"와 같은 원리
• GitHub 리뷰 봇 폐기(누락·얕은 finding) → 로컬 리뷰 디폴트 · adversarial 멀티에이전트는 큰 변경 한정 옵트인

● 리뷰 완료 (신규 세션, Tier D). 결과:
codex 리뷰 finding
- P1: 없음
- P2 (line 153, 케이스 B): same-type overwrite 테스트가 GUID·이름만 확인 → 구현이 CopySerialized(인스턴스 유지) 대신 "삭제 후 재생성"으로 퇴행해도 통과할 수 있음. 케이스 C에서 실측했던 CreateAsset 경로도 GUID를 유지하므로, 이 지적은 정확합니다. GUID만으로는 CopySerialized 경로를 진짜로 고정 못 함.
  - 권고: overwrite 전 로드한 existing 인스턴스와 overwrite 후 asset이 Assert.AreSame인지 확인 → identity 보존 직접 증명
- P3 (line 48): BattleConfigData 실제 게임 타입 결합 → 무관한 타입명 변경/삭제로 fixture가 깨질 수 있음. 테스트 내부 더미 ScriptableObject로 대체 권고
- P3 (line 29): 어셈블리 해석이 static initializer + First() → 부재 시 SetUp assert 전에 TypeInitializationException으로 원인이 흐려짐. FirstOrDefault + SetUp에서 명시 실패 권고
리뷰가 통과시킨 것: confirmOverwrite 분기 타격(콜백 호출 여부 포함), 슬라이스 104개 보증, temp 정리, DefaultOutputFolder 비오염, 네임스페이스/asmdef 경계.
제 판단
P2는 반영이 맞습니다 — 이 테스트의 존재 이유가 "overwrite 분기 고정"인데, GUID만 보면 CopySerialized 경로가 퇴행해도 못 잡습니다. AreSame으로 인스턴스 identity까지 봐야 진짜로 고정됩니다. P3 2개도 결합 제거·진단 개선이라 같이 반영하는 게 깔끔합니다(type:test라 프로덕션 영향 없음).
3개 finding 전부 codex에 위임해 반영 → 재검증 → PR 생성으로 진행하겠습니다. 이대로 갈까요?

2막 · 무인화 ⑦-1

issue-agent — 자는 동안 PR이 올라온다

맥미니에서 도는 무인 에이전트가 이슈를 집어 → 브랜치 분기 → 수정 → 검증 → 자동 PR

정책은 repo의 .issue-agent.yml에 코드로 선언:

auto_eligible_labels: [type:cleanup, type:bug, type:tech-debt]
exclude_labels: [type:feature]        # 기획 판단이 필요한 건 안 집음
max_diff_lines: 60                    # 작은 수정만
require_repro_test: true              # 재현 테스트 없으면 PR 불가
verify:
  type: unity
  commands: [refresh, console]        # 로컬 Unity로 컴파일·콘솔 검증까지

• 1막의 복선 회수: type:* 라벨 컨벤션이 정리되어 있으니 기계가 "집어도 되는 일"을 판별
• feature를 제외하는 이유: 신규 기능 = 기획 결정 필요 = 사람 영역

2막 · 무인화 ⑦-2

실물 — 자는 동안 벌어진 일

왼쪽: issue-agent가 올린 실제 PR — Closes #N, 변경 요약·컴파일 에러 0까지 스스로 리포트
오른쪽: 새벽 3시 21분 Discord 알림 — 이슈 23개 분류 → PR 1건. 60줄 상한 초과로 abort된 이슈는
사람에게 넘김(needs-human) — 다음 장의 가드레일이 실제로 작동한 순간

2막 · 무인화 ⑦-3

무인화의 가드레일 — 자율성 ↑ ⇒ 가드레일 ↑

auto_merge:
  enabled: false                          # 머지는 무조건 사람
  forbid_paths: [Tests/, .github/, CODEOWNERS]
notify:
  on_failure: true

• 자동 머지 off — 에이전트는 PR까지만. 최종 승인은 사람
• Tests/ 수정 금지 = 테스트 게이밍 방어
  • 에이전트가 "테스트를 고쳐서" 통과시키는 고전적 실패 모드를 경로 차단으로 봉쇄
• .github/, CODEOWNERS 금지 = 에이전트가 자기 가드레일을 못 고침
• require_repro_test — 버그 수정엔 재현 테스트가 따라와야 함 (수정 증명 강제)

교훈: 자율성을 한 단계 올릴 때마다 가드레일도 한 단계 올린다.
사람이 보는 PR과 무인 PR의 신뢰 수준은 다르고, 정책이 그 차이를 흡수

3막 · 왜 굴러가는가 ①

AI 친화 컨벤션 (런타임) — grep 가능한 규칙

장르 선택부터 AI 친화적 — 결정론적 턴제 SRPG: UI/UX를 제외한 대부분 영역을 AI가 반드시 재현 가능
→ 같은 시드 = 같은 전투 결과 → 리플레이·스킵 패리티·밸런스 자동 시뮬(autoloop 마일스톤)이 성립하는 기반

그 위에서, 사람에게 좋은 컨벤션 ≈ AI에게 좋은 컨벤션. 차이점: AI는 기계적으로 판별 가능한 규칙을 잘 지킴

• 반대로 경계 규칙("기획으로 풀 일 코드 보정 금지" 등)은 AI의 과잉 친절(멋대로 방어 코드) 차단용

3막 · 왜 굴러가는가 ②

코드 구성 — 전체 코드의 37%가 테스트

게임 프로젝트치고는 이례적인 비중 — 게임판은 전통적으로 테스트 코드가 희박한 동네.
여기서는 테스트가 곧 AI가 자기 변경을 증명하는 수단이고, 작성 한계비용도 낮아서(AI가 쓴다)
버그 수정마다 재현 테스트가 따라붙는 문화가 유지됨 → 다음 장: 이 테스트 더미를 지탱하는 룰

3막 · 왜 굴러가는가 ③

AI 친화 컨벤션 (테스트) — AI의 자기 검증 수단

테스트는 AI가 자기 변경을 증명하는 도구 → "AI가 어디까지 검증 가능한지"를 룰로 못박음

• EditMode/PlayMode 경계 명문화: 순수 로직=EditMode, 씬·페이즈 라우팅=PlayMode/런타임
  • 경계를 모르면 AI가 "테스트 불가"를 "테스트 통과"처럼 보고하는 사고가 남
• 동작 변경 시 옛 동작을 단정하는 테스트 전수 grep — AI는 만진 코드 근처 테스트만 갱신하는 습성
• 공개 API 제거 전 소비처 grep은 Tests/ 포함 — 리플렉션 테스트는 컴파일은 통과, 런타임만 깨짐
• "에러가 안 남" ≠ "작동함" — 데이터가 없어서 경로가 실행 안 된 것일 수 있음.
  실제 데이터로 트리거되는지까지 확인

이 항목들의 공통점: 전부 한 번 이상 실제로 당한 것들 (→ 다음 챕터)

3막 · 왜 굴러가는가 ④

컨텍스트 주입 3계층 — 룰의 위치가 준수율을 결정

• 단일 진실 소스: 같은 룰을 두 곳에 안 씀. AGENTS.md는 내용 없이 포인터만
• Codex에는 hook이 같은 룰을 주입 — claude-rules-bridge hook이 도구 호출이 접근하는 파일 경로에
  매칭되는 rules를 그 자리에서 로드 → 같은 규칙, 같은 파일 한 벌. 룰을 고치면 양쪽 동시 반영
• repo에는 코드만, 문서는 Obsidian vault로 분리 — 기획·SPEC/DESIGN/PLAN 전부 vault,
  Syncthing이 맥북(휴먼 게이트) ↔ 맥미니(무인 에이전트)를 상시 동기화 — 어느 쪽 에이전트든 항상 최신 문서
• 세션 간 자동 메모리 — 사실·교훈이 파일로 축적돼 다음 세션에 자동 주입

3막 · 어떻게 유지되는가 ①

실수 적립 루프 — 이 발표의 핵심

"AI는 같은 실수를 반복한다" → 반복을 구조적으로 차단하는 4단 사다리:

포인트: 사다리를 다 올리지 않음. 대부분 ①에서 끝나고, 반복되는 것만 ②③으로 승격

3막 · 어떻게 유지되는가 ②

실제 사례 — 앞에서 본 룰들, 전부 사고에서 나왔다

• ④-2의 위임 브리핑 상시 조항, ⑦-3의 가드레일 — 전부 이 루프의 산출물
• 도구는 베낄 수 있지만, 이 적립 루프가 워크플로의 지속가능성 본체

클로징

한계와 사람의 몫

여전히 사람이 하는 것 — 그리고 앞으로도 사람이 해야 하는 것:

• 기획 결정 — AI는 추천과 근거까지, 결정은 사람. 두 AI가 합의해도 mandate가 아님
• UI 시각 디자인 fine-tune — 레이아웃·색·spacing. AI는 구조와 컨벤션까지만
• 머지 최종 승인 — 사람 PR이든 무인 PR이든 예외 없음
• 리뷰 finding 채택 판단 — 리뷰 지적은 정보이지 명령이 아님
• 사고의 첫 발견 — 루프는 적립을 자동화하지, 감지까지 자동화하진 못함

현재의 한계:

• 무인 에이전트는 60줄 이하 소형 수정까지 — 판단이 필요한 작업은 아직 못 맡김
• 런타임 "느낌"의 검증(타격감·연출 품질)은 결국 사람 눈
• 파이프라인 유지비: 룰·메모리·문서의 정원 관리가 상시 필요 (방치하면 false positive 공장)

클로징

정리

가져갈 것 3가지:

1. 도구가 아니라 파이프라인 — 단계마다 산출물과 게이트가 있어야 AI가 폭주하지 않는다
2. 독립성과 자기 검증이 품질을 만든다 — 구현/리뷰 세션 분리, AI가 자기 변경을 직접 구동
3. 실패를 시스템에 적립하라 — 메모리 → 룰 → 기계 강제의 사다리.
   이게 없으면 나머지 전부가 같은 사고를 반복하는 비싼 장난감