개요

OpenAI 엔지니어링 블로그 글 「하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기」(Ryan Lopopolo, 2026-02-11)를 단원별로 공부하며 정리한 글이다.
- 원문: https://openai.com/ko-KR/index/harness-engineering/
원문을 옮긴 글이 아니라, 단원마다 요지 + 내가 이해한 방식 + 곁가지로 찾아본 것을 적었다.
한 줄 요약: 에이전트가 일을 잘하게 만드는 건 모델이 아니라 모델을 둘러싼 환경(하네스)이고, 엔지니어의 일은 코드를 쓰는 것에서 그 환경을 설계하는 것으로 바뀐다.

하네스란?

harness는 원래 말이나 개가 수레를 끌 수 있게 몸에 채우는 마구(馬具)다. 힘은 말이 내고, 그 힘을 원하는 방향으로 쓰게 만드는 게 마구다.
AI 에이전트에서는 모델을 제외한 나머지 전부를 하네스라고 부른다.
- 모델이 쓸 수 있는 도구(파일 읽기, 빌드, 시뮬레이터 조작…)
- 모델이 읽는 문서(AGENTS.md, CLAUDE.md, 설계 문서)
- 모델의 실수를 잡는 장치(린트, 테스트, CI, 훅)
- 결과를 다시 모델에게 돌려주는 피드백 루프
모델 회사는 모델을 좋게 만들고, 하네스 엔지니어링은 같은 모델로 더 많은 일을 끝까지 해내게 만든다.

서문: 사람이 조정하고, 에이전트가 수행한다

요지

5개월 동안 사람이 직접 쓴 코드 0줄로 실제 사용자가 쓰는 내부 베타 제품을 만들었다.
손으로 짰을 때보다 약 1/10 시간이 걸렸다고 추정한다.
엔지니어의 일이 바뀌었다. 환경을 설계하고, 의도를 명시하고, 피드백 루프를 만든다.
가장 부족한 자원은 사람의 시간과 주의력이다.

생각해 볼 것

“1/10”은 측정이 아니라 추정이다. 그리고 빈 저장소에서 시작한 그린필드 프로젝트다. 오래된 코드가 쌓인 브라운필드에서는 같은 결과를 기대하기 어렵다.
“사람 주의력이 가장 부족하다”는 제약 이론(Theory of Constraints)으로 읽으면 쉽다. 시스템 전체 속도는 가장 느린 지점(병목)이 정한다. 에이전트 시대의 병목은 사람이다.

1. 빈 git 저장소에서 시작

요지

첫 커밋은 2025년 8월 말. 저장소 뼈대(구조, CI, 포맷 규칙, 패키지 설정, 프레임워크)와 첫 AGENTS.md까지 Codex가 만들었다.
5개월 뒤 약 100만 줄, 엔지니어 3명 → 7명, PR 약 1,500개. 엔지니어 1인당 하루 3.5 PR.
사람이 늘수록 1인당 처리량이 오히려 늘었다.

생각해 볼 것

100만 줄 ÷ 1,500 PR ≈ PR 하나에 약 670줄. 사람 팀 기준으로는 리뷰하기 버거운 크기다.
브룩스의 법칙: 늦어진 프로젝트에 사람을 넣으면 소통 비용 때문에 더 늦어진다. 여기서는 반대 결과가 나왔는데, 사람끼리 직접 협업하는 대신 각자 에이전트를 지휘해서 소통 경로가 덜 늘었기 때문으로 보인다.
굿하트의 법칙: 지표가 목표가 되면 좋은 지표가 아니게 된다. PR 수, 코드 줄 수는 쉽게 부풀릴 수 있어서 원문도 “실제 사용자가 쓰는 제품”이라는 점을 함께 강조한다.

2. 엔지니어의 역할 재정의

요지

초반에 느렸던 이유는 모델이 부족해서가 아니라 도구, 추상화, 구조가 빠져 있었기 때문이다.
그래서 깊이 우선으로 빌딩 블록부터 만들었다.
에이전트가 막히면 “더 열심히 해 봐”가 아니라 “무엇이 빠졌지?”를 묻는다.
사람은 프롬프트로만 일하고, 리뷰도 점점 에이전트끼리 하게 했다.

핵심 개념

legible vs enforceable
- legible: 에이전트가 읽으면 알 수 있다 (문서)
- enforceable: 에이전트가 안 지킬 수 없다 (린트, 테스트, CI)
- 문서는 잊히거나 무시될 수 있다. 중요한 규칙은 결국 강제로 가야 한다.
Ralph Wiggum 루프: 에이전트가 “끝났다”고 하면 같은 프롬프트로 다시 돌려서, 진짜 끝날 때까지 반복시키는 기법. (Claude Code에서는 Stop 훅으로 구현할 수 있다.)
사람 리뷰를 뺄 수 있는 곳 / 없는 곳
- 되돌릴 수 있고 영향이 작으면 → 에이전트 리뷰로 충분
- 되돌리기 어렵고 영향이 크면(보안, 암호화, 라이선스, 외부에 배포되는 바이너리) → 사람 리뷰가 필요
- 아마존식 표현으로 양방향 문(two-way door) vs 한 방향 문(one-way door)

3. 애플리케이션을 에이전트가 읽을 수 있게

요지

코드 처리량이 늘자 사람의 QA가 병목이 됐다.
그래서 에이전트가 앱 화면, 로그, 메트릭을 직접 보게 만들었다.
- worktree마다 앱을 따로 띄운다.
- Chrome DevTools Protocol로 DOM 스냅샷, 스크린샷, 화면 이동을 한다.
- worktree마다 임시 관측 환경(로그·메트릭·트레이스)을 띄우고, 에이전트가 쿼리로 조회한다.
“시작 시간 800ms 이하”, “이 구간은 2초 이하” 같은 숫자 목표를 주면 에이전트가 스스로 측정하고 고친다.
그 결과 에이전트가 사람이 자는 동안 6시간 넘게 혼자 일하기도 했다.

iOS로 옮기면

웹 (원문)	iOS
DOM 스냅샷	접근성(AX) 트리 덤프
스크린샷	`simctl io screenshot`
클릭·이동	AX 기반 탭 도구 (예: axe)
트레이스 구간	`os_signpost` + Instruments / `xctrace`

접근성 라벨은 시각장애인용이기도 하지만, 이제는 에이전트가 화면을 읽는 통로이기도 하다. 라벨 없는 아이콘 버튼은 에이전트에게 보이지 않는다.
시뮬레이터에서 잰 시간은 실기기와 다르다. 전/후 비교(상대값)로만 쓴다.

4. 저장소 지식을 기록 시스템으로

요지

에이전트의 컨텍스트는 책상과 같다. 넓지 않다. 1,000쪽짜리 매뉴얼이 아니라 지도를 줘야 한다.
거대한 AGENTS.md 하나로 몰아넣으면 실패한다.
1. 책상(컨텍스트)이 모자란다. 긴 문서는 중간 내용을 놓친다(“Lost in the Middle”).
2. 규칙이 너무 많으면 에이전트가 국소적인 패턴 맞추기에 빠진다.
3. 금방 낡는다. 낡은 문서는 오히려 잘못 이끈다.
4. 기계로 검사할 수 없다(빠진 곳, 낡은 곳, 담당자, 링크).
그래서 AGENTS.md는 약 100줄짜리 목차로 두고, 실제 지식은 docs/ 아래에 나눴다.

AGENTS.md            ← 지도 (약 100줄)
ARCHITECTURE.md
docs/
  design-docs/       ← 설계 문서
  exec-plans/
    active/          ← 진행 중인 계획
    completed/
    tech-debt-tracker
  generated/         ← DB 스키마 등 자동 생성 문서
  product-specs/
  references/        ← 외부 라이브러리 llms.txt 등
  QUALITY_SCORE, RELIABILITY, SECURITY ...

계획(plan)도 일급 산출물이다. 진행 상황과 결정 기록(decision log)을 저장소에 남긴다.
문서 린터와 문서 정원사 에이전트가 낡은 문서를 찾아 수정 PR을 연다.

핵심 개념

점진적 공개(progressive disclosure): 처음엔 지도만 주고, 필요할 때 해당 문서를 열게 한다.
기록 시스템(system of record): “정답은 여기에 있다”고 모두가 합의한 한 곳. 사람 머릿속, 메신저, 위키가 아니라 저장소.

5. 목표는 에이전트 가독성

요지

에이전트가 접근할 수 없는 것은 존재하지 않는 것과 같다. 메신저 대화, 구글 문서, 사람 머릿속 지식은 에이전트에게 없다.
판단 기준: “3개월 뒤 들어온 신입이 저장소만 보고 알 수 있나?”
기술 선택도 에이전트 기준으로 한다.
- 지루한 기술(boring technology): 오래되고 널리 쓰여서 모델이 이미 잘 아는 기술이 유리하다.
- 작은 유틸리티는 외부 라이브러리 대신 저장소 안에 직접 구현하기도 한다. 동작을 저장소 안에서 다 볼 수 있고, 에이전트가 고칠 수 있기 때문이다.

생각해 볼 것

내가 Claude에게 남긴 개인 메모리도 팀원 에이전트 입장에서는 “사람 머릿속”이다. 팀이 알아야 하는 규칙이면 저장소로 옮겨야 한다.
외부 라이브러리를 직접 빌드해서 쓰는데 사내 패치가 문서 없이 들어가 있으면, 라이브러리를 새로 받는 순간 패치가 조용히 사라진다. “저장소 안에 두고 보이게 하라”가 왜 중요한지 보여 주는 사례다.

6. 아키텍처와 취향을 강제하기

요지

구현이 아니라 불변 조건(invariant)을 강제한다.
- 예: 경계에서 데이터를 파싱한다(Parse, don’t validate). Swift로 치면 JSON을 Codable 타입으로 바로 디코딩하고, 안쪽에서는 타입만 믿는 것.
도메인마다 레이어를 고정하고 의존 방향을 한쪽으로만 허용한다.
- Types → Config → Repo → Service → Runtime → UI
- 인증, 텔레메트리, 피처 플래그 같은 공통 관심사는 Providers로 주입한다.
- 사람 팀이면 엔지니어가 수백 명이 될 때나 하는 구조를, 에이전트 팀은 첫날부터 필요로 한다.
맞춤 린터로 “취향 불변 조건”을 강제한다: 구조화된 로깅, 스키마·타입 이름 규칙, 파일 크기 제한, 플랫폼별 안정성 요구사항.
린트 에러 메시지에 고치는 방법을 써 넣어서, 에이전트 컨텍스트에 필요한 순간에만 지침을 넣는다.
사람에게는 깐깐한 규칙이 에이전트에게는 지렛대다. 한 번 만들면 모든 곳에 적용된다.
중앙에서는 경계를, 현장에서는 자율을. 경계 안에서 코드가 사람 취향과 달라도 괜찮다.
사람 취향은 리뷰 코멘트, 리팩터링, 버그를 통해 문서로, 문서로 부족하면 코드로 승격한다.

에이전트용 좋은 에러 메시지

error: statusBarOrientation 사용 금지 (SignPad.mm:214)
  왜:   iOS 27에서 항상 같은 값을 돌려줌
  대신: view.window.windowScene.interfaceOrientation
  참고: docs/pitfalls.md#ios27-orientation

규칙 100개를 CLAUDE.md에 다 쓰면 항상 책상을 차지한다.
린트로 옮기면 평소에는 자리를 안 차지하다가, 어긴 순간에만 그 규칙 하나가 나타난다. 그리고 안 고치면 빌드가 안 된다.

승격 사다리 — 그리고 “누구에게 적용되나”

강제력:

① 사람 머릿속       나만 앎
② 리뷰 코멘트       이번 PR만
③ 문서              읽으면 앎 (legible)
④ 린트·테스트·훅    어기면 막힘 (enforceable)

같은 지적이 2~3번 반복되면 한 단계 올린다.
기계로 판정할 수 없는 취향은 ③에 머물거나 에이전트 리뷰로 처리한다.

여기에 축이 하나 더 있다. 적용 범위다.

	나만	Claude Code 쓰는 팀원	모든 팀원·모든 도구
③ 읽으면 앎	개인 메모리	—	저장소의 `AGENTS.md`, `docs/`
④ 어기면 막힘	`~/.claude` 훅	저장소의 `.claude/settings.json` 훅	CI

개인 훅은 강제력은 있어도 나 혼자만 지킨다.
팀에 퍼뜨리려면 문서는 저장소로, 강제는 CI로 가야 한다.
단, CI도 “실패해도 머지 가능”으로 설정돼 있으면 아직 정보 제공 단계다. 머지 차단을 켜야 진짜 ④다.

7. 처리량이 머지 철학을 바꾼다

요지

처리량이 늘자 기존 엔지니어링 규범이 역효과를 냈다.
그래서 머지를 막는 관문을 최소한으로 두고, PR 수명을 짧게 하고, 불안정한(flaky) 테스트는 다시 돌려서 넘어간다.
에이전트 처리량이 사람 주의력을 훨씬 넘는 환경에서는 고치는 비용은 싸고, 기다리는 비용은 비싸다.
처리량이 낮은 환경에서는 이렇게 하면 안 된다.

생각해 볼 것

대기열로 보면 쉽다. 들어오는 속도(에이전트 PR)가 처리 속도(사람 리뷰)보다 계속 빠르면 대기열은 끝없이 길어진다.
flaky 테스트를 재실행으로 넘기면 진짜 경쟁 상태 버그를 묻을 위험이 있다. 보통은 넘기되 따로 기록(격리)하고 나중에 정리한다.
핵심은 “관문을 줄여라”가 아니라 “관문 수는 고치는 비용과 기다리는 비용의 비율로 정하라”다.
- 외부 고객에게 바이너리로 배포되는 SDK처럼 되돌리기 어려운 환경은 반대로 관문을 유지하거나 늘리는 게 맞다.

8. “에이전트가 만들었다”의 실제 의미

요지

제품 코드뿐 아니라 전부를 에이전트가 만든다: 테스트, CI 설정, 릴리스 도구, 내부 개발 도구, 문서, 설계 기록, 평가 하네스, 리뷰 코멘트와 답변, 저장소 관리 스크립트, 대시보드 정의 파일.
사람은 다른 층에서 일한다: 우선순위 정하기, 사용자 피드백을 수용 기준으로 바꾸기, 결과 검증.
에이전트가 막히면 그걸 신호로 본다. 빠진 도구·가드레일·문서를 찾고, 그 보완도 에이전트가 작성해서 저장소에 넣는다.
에이전트는 사람과 같은 도구(git, gh, 리뷰 화면)를 쓰고, 자기 PR을 직접 머지하기도 한다.

핵심 개념

일부만 사람이 관리하면 그 부분이 섬이 된다. 에이전트가 손댈 수 있는지 헷갈리고, 사람 주의력을 계속 먹는다.
평가 하네스: 출력이 “맞다/틀리다”가 아니라 “100개 중 몇 개를 풀었나”를 재는 테스트 묶음.
수용 기준(acceptance criteria): “이 조건을 만족하면 완료”라는 검증 가능한 문장. Gherkin의 Given / When / Then이 대표적인 형식이다.
- “서명창이 이상해요” → “iPad에서 서명 중 회전하면, 회전이 끝난 뒤 서명 패드가 새 방향 크기에 맞는다”

9. 자율성 수준의 증가

요지

테스트, 검증, 리뷰, 피드백 처리, 복구가 시스템에 하나씩 들어가면서 임계점을 넘었다.
이제 프롬프트 한 번으로 에이전트가 끝까지 간다.
1. 현재 상태 검증
2. 버그 재현
3. 실패 영상 녹화
4. 수정
5. 앱 실행으로 검증
6. 해결 영상 녹화
7. PR 열기
8. 피드백 대응
9. 빌드 실패 감지·수정
10. 판단이 필요할 때만 사람에게 넘기기
11. 머지
단, 이 저장소의 구조와 도구 덕분이다. 비슷한 투자 없이 일반화하면 안 된다.

생각해 볼 것

11단계 중 하나라도 사람이 해야 하면 거기서 멈추고 사람을 기다린다. 그래서 자율성은 조금씩이 아니라 한꺼번에 넘어간다.
영상은 사람을 위한 증거다. diff 수백 줄보다 전/후 영상 30초가 훨씬 빨리 검증된다.
“판단이 필요한 경우”는 미리 정의되어 있어야 한다. 없으면 너무 자주 묻거나, 물어야 할 걸 안 묻는다.
가져갈 건 “11단계 자동화”가 아니라 “내 작업 체인에서 사람이 끼어야 하는 칸이 어디인가”를 그려 보는 것이다.

10. 엔트로피와 가비지 컬렉션

요지

에이전트는 저장소에 있는 패턴을 나쁜 것까지 복제한다. 시간이 지나면 드리프트가 생긴다.
처음엔 매주 금요일(일주일의 20%)을 “AI 슬롭” 청소에 썼다. 확장되지 않았다.
대신 황금 원칙을 저장소에 넣고, 정기 청소를 자동화했다.
1. 불변 조건을 한곳에 두도록, 직접 만든 헬퍼보다 공유 유틸리티를 쓴다.
2. 데이터를 YOLO 스타일로 더듬지 않는다. 경계에서 검증하거나 타입 있는 SDK를 쓴다.
백그라운드 에이전트가 위반을 찾고, 품질 등급을 갱신하고, 1분 안에 리뷰할 수 있는 작은 리팩터링 PR을 만든다. 대부분 자동 머지된다.
기술 부채는 고금리 대출이다. 몰아서 갚기보다 매일 조금씩 갚는다.

생각해 볼 것

에이전트는 예시가 많은 패턴을 “이 저장소의 방식”으로 판단한다. 나쁜 패턴이 26곳 있으면 27번째를 만든다. 나쁜 패턴이 스스로 번식하는 구조다.
그래서 에이전트 시대에는 기술 부채의 금리 자체가 더 높다.
YOLO 스타일 vs 경계 파싱

// YOLO: 모양을 추측해서 꺼냄
let name = (json["data"] as! [String: Any])["user_name"] as! String

// 경계에서 파싱: 모양을 타입으로 선언
struct UserResponse: Decodable { let userName: String }
let user = try JSONDecoder().decode(UserResponse.self, from: data)

래칫(ratchet): 쌓인 부채를 바로 다 갚기 어려우면, 먼저 “사용 개수가 기준선보다 늘면 CI 실패”로 번식부터 막고, 그다음 조금씩 줄인다. 숫자가 한 방향으로만 움직이게 하는 톱니다.
5단원의 “직접 구현”과 10단원의 “공유 유틸리티”는 모순이 아니다. 합치면 “저장소 안에 정본 한 벌”이다.
단순한 표현 코드는 중복돼도 괜찮지만, 불변 조건을 담은 코드(재시도 정책, 파싱 규칙, 권한 확인)는 반드시 한곳에 있어야 한다.

11. 아직 배우고 있는 것

요지

내부 출시 단계까지는 잘 통했다.
아직 모르는 것: 몇 년 뒤 아키텍처 일관성이 어떻게 될지, 사람 판단이 어디서 가장 효과가 큰지, 모델이 좋아지면 이 시스템이 어떻게 바뀔지.
분명해진 것: 규율은 여전히 필요하지만, 코드보다 스캐폴딩에서 드러난다.
가장 어려운 과제는 환경, 피드백 루프, 제어 시스템을 설계하는 것이다.

생각해 볼 것

레만의 법칙: 계속 쓰이는 소프트웨어는 일부러 줄이지 않으면 복잡도가 계속 늘어난다. 10단원 엔트로피를 수십 년 전에 관찰한 것이다. 5개월짜리 실험은 아직 이걸 겪지 않았다. 오래된 코드베이스는 이미 겪은 상태다.
쓴 교훈(The Bitter Lesson, Rich Sutton): 사람이 공들여 넣은 요령은 결국 범용 방법에 밀려난다. 하네스도 그럴까? 두 종류로 나누면 답이 갈린다.

	모델 보완형	환경 정의형
하는 일	모델의 약점을 메움	이 프로젝트가 무엇인지 정의
예시	점진적 공개, 단계 쪼개기, “이 함정 조심”	레이어 규칙, 경계 파싱, 수용 기준, 테스트, 관측 도구
모델이 좋아지면	줄어들 수 있음	그대로 필요함

투자 순서는 환경 정의형부터. 모델이 바뀌어도 투자가 날아가지 않는다.
제어 시스템은 비유가 아니라 진짜 제어 공학 용어다.

제어 시스템	하네스	단원
목표	수용 기준, 숫자 목표	3, 8
센서	관측 도구, 화면 스냅샷, 로그	3
비교기	린트, 테스트, 구조 검사	6
작동기	에이전트	전체
주기적 보정	백그라운드 청소	10

센서가 없으면 제어가 불가능하다. 3단원이 앞에 나온 이유다.

곁가지로 공부한 것

단계 성공률은 곱해진다

단계마다 독립적으로 성공한다고 가정하면, 전체 성공률 = 단계 성공률^{단계 수}.

단계 성공률	5번	10번	20번	50번	100번
95%	77%	60%	36%	8%	0.6%
99%	95%	90%	82%	61%	37%
99.9%	99.5%	99%	98%	95%	90.5%

단계 성공률이 몇 %p만 올라도 긴 작업의 성공률은 몇 배로 뛴다. 2025년 말 에이전트가 갑자기 쓸 만해진 이유를 설명할 때 자주 쓰는 계산이다.
하지만 이건 “한 번 틀리면 끝”이라는 가정이다. 실제로는 빌드 에러, 테스트 실패를 보고 다시 고친다. 단계 성공률 95%에 검사가 실수를 잡아 다시 시도하게 하면:

검사가 실수를 잡는 비율	실질 단계 성공률	20번 성공률
0%	95%	36%
50%	97.4%	59%
80%	98.8%	79%
90%	99.3%	87%

모델을 바꾸지 않고 검사만 붙여서 36% → 87%.
모델 회사는 왼쪽 숫자(95% → 99%)를 올리고, 하네스 엔지니어링은 “검사가 잡는 비율”을 올린다. 이 글 전체의 요점이 이 표 하나에 있다.

훅(hook)

Claude Code가 특정 시점에 자동으로 실행하는 셸 명령이다. 모델이 “기억해서” 지키는 게 아니라 하네스가 강제로 실행한다.
주요 시점: PreToolUse(도구 실행 전 — 막을 수 있음), PostToolUse, UserPromptSubmit, Stop(끝내려 할 때), SessionStart, SubagentStop.
명령이 종료 코드 2로 끝나면 해당 동작을 막고, 에러 메시지가 모델에게 전달된다.
범위
- ~/.claude/settings.json — 나만
- <저장소>/.claude/settings.json — 커밋하면 팀 공유
- <저장소>/.claude/settings.local.json — 나만, git 제외
함정: 프로젝트 설정은 Claude를 실행한 폴더 기준으로 읽힌다.

CI / CD

CI = Continuous Integration(지속적 통합). 코드를 자주 합치고, 합칠 때마다 서버가 자동으로 빌드·테스트한다. 원래는 몇 주씩 따로 작업하다 한꺼번에 합칠 때 터지던 “통합 지옥”을 피하려고 생겼다.
CD는 두 가지 뜻이 있다.
- Continuous Delivery: 통과하면 언제든 배포할 수 있게 패키징까지. 배포 버튼은 사람이 누른다.
- Continuous Deployment: 통과하면 사람 개입 없이 배포까지.
iOS로 치면: MR마다 xcodebuild build/test(CI) → TestFlight 자동 업로드(Delivery) → 심사 제출까지 자동(Deployment, 드묾).
GitLab은 저장소 루트의 .gitlab-ci.yml, GitHub은 .github/workflows/. 실제 실행하는 기계는 러너. iOS 빌드는 macOS 러너가 필요하다.

grep이 파일을 “조용히” 건너뛰는 함정

오래된 C/C++ 코드에는 한글 주석이 CP949(EUC-KR 계열)로 저장된 파일이 많다.
일부 grep 구현은 바이너리 파일 무시 옵션(-I)이 켜져 있으면, UTF-8로 해석되지 않는 바이트를 보고 파일 전체를 바이너리로 판단해 건너뛴다. “매치 0건”이 아니라 “아예 안 봄”이다.
같은 ‘한’ 글자도 바이트가 다르다: UTF-8 ED 95 9C, CP949 C7 D1. 영문 ‘A’는 둘 다 41.
에이전트가 이 결과를 믿으면 “그런 함수는 없다”고 잘못 결론 낸다. rg로 교차 확인한다.
원문 8단원의 “막힘 = 신호 → 빠진 것을 저장소에” 흐름의 좋은 예다. 이 함정은 개인 메모리가 아니라 저장소 문서에 있어야 팀원 에이전트도 피한다.

worktree vs clone

git clone을 두 번 하면 .git 데이터가 두 벌이 된다. 큰 저장소면 디스크도 두 배.
git worktree add는 .git을 하나 공유하면서 작업 폴더만 여러 개 만든다. 브랜치, stash, 커밋이 서로 보인다.
원문 3단원처럼 작업마다 독립된 폴더에서 앱을 띄우는 구조의 기반이다.

os_signpost

코드 구간에 시작/끝 표시를 남겨서 Instruments에서 시간을 재는 도구다.
xctrace export로 결과를 텍스트로 뽑을 수 있어서 에이전트가 직접 읽을 수 있다. 원문 3단원의 “2초 이하” 같은 숫자 목표를 iOS에서 구현하는 방법이다.
XCTest의 XCTOSSignpostMetric으로 성능 테스트에도 쓸 수 있다.

한 장 정리

단원	한 줄
서문	사람은 조정, 에이전트는 수행. 가장 귀한 건 사람 주의력
1	빈 저장소에서 5개월, 100만 줄, 사람 코드 0
2	막히면 모델 탓 말고 빠진 도구를 찾아라
3	에이전트가 앱·로그를 직접 보게 하라
4	`AGENTS.md`는 지도, 지식은 `docs/`에
5	에이전트가 못 보면 존재하지 않는다
6	경계는 코드로 강제, 안쪽은 자율, 반복되는 취향은 승격
7	관문 수는 고치는 비용 vs 기다리는 비용으로 정하라
8	전부 에이전트가, 사람은 수용 기준과 검증
9	체인에서 사람이 끼는 칸을 없애면 임계점을 넘는다
10	나쁜 패턴은 번식한다. 매일 조금씩 청소하라
11	규율은 스캐폴딩에. 하네스 = 제어 시스템

다음에 읽을 글

같은 주제를 Anthropic은 어떻게 풀었는지 보려고 고른 목록이다. 한 번에 한 편씩 읽는다.
출처: https://www.anthropic.com/engineering

1순위 — 이 글과 바로 이어지는 것

Harness design for long-running application development (2026-03-24) — 다음에 읽을 글
Effective harnesses for long-running agents (2025-11-26) — 위 글의 전편. 필요하면 보충
Redesigning source control at Anthropic (2026-10-13) — 머지가 10배 늘자 소스 관리가 병목. 7단원과 짝
Effective context engineering for AI agents (2025-09-29) — 4단원과 짝
Building a C compiler with a team of parallel Claudes (2026-02-05) — 에이전트 팀으로 큰 프로젝트

2순위 — 연결되는 주제

Writing effective tools for agents — with agents (2025-09-11) — MCP 공부와 연결
Code execution with MCP (2025-11-04)
Equipping agents for the real world with Agent Skills (2025-10-16)
The components of agent memory (2026-11-06)
Beyond permission prompts: making Claude Code more secure and autonomous (2025-10-20)
How we built Claude Code auto mode (2026-03-25)
Demystifying evals for AI agents (2026-01-09) — 8단원 “평가 하네스”

3순위 — 기초

Claude Code: Best practices for agentic coding (2025-04-18)
How we built our multi-agent research system (2025-06-13)

같이 보면 좋은 것

OpenAI의 Codex 네이티브 개발 가이드 모음(iOS/macOS 시뮬레이터 디버깅, App Intents 등): https://learn.chatgpt.com