Anthropic의 엔지니어들도 똑같은 벽에 부딪혔다 — 그리고 그들의 해결책
원본 영상: Anthropic’s Engineers Hit the Same Wall You Did — Here’s Their Fix
채널: Crafter’s Lab (Daniel)
날짜: 2026년 3월 13일
태그: #claudecode #anthropic #harnessengineering
개요
이 영상은 iOS 개발자 Daniel이 Anthropic의 엔지니어링 블로그 포스트를 분석하며, Claude Code와 같은 AI 에이전트를 실전에서 사용할 때 공통적으로 발생하는 세 가지 핵심 문제와 Anthropic이 이를 어떻게 해결했는지를 설명하는 내용이다. 핵심 메시지는 단순하다. Claude를 만든 Anthropic조차도 우리가 겪는 똑같은 문제를 겪었고, 그 해결책은 마법이 아닌 구조(structure)였다.
배경: 이 영상이 중요한 이유
Anthropic은 자사의 엔지니어링 블로그를 통해 Claude Agent SDK를 장시간 운용하며 마주친 구체적인 실패 사례들을 솔직하게 공개했다. 이 포스트는 단순한 기능 소개가 아니라, 최첨단 AI 모델을 만든 회사조차 에이전트 운용에 있어서 외부 구조(파일, 지시문, 테스트 체계)가 없으면 실패한다는 사실을 인정한 것이다.
Daniel은 이를 “솔로 개발자에 대한 Anthropic의 공식 검증”이라고 표현하며, 이미 CLAUDE.md나 progress.md 같은 파일 기반 세션 관리 시스템을 독립적으로 구축해 온 개발자들의 접근법이 올바른 방향이었음을 입증한다고 강조한다.
세 가지 핵심 실패 패턴과 해결책
1. 세션 간 컨텍스트 소실 (Context Loss Between Sessions)
문제: 에이전트는 매번 백지에서 시작한다
AI 에이전트가 장기 프로젝트를 수행할 때 가장 근본적인 문제는 컨텍스트 윈도우(context window)가 세션이 끝나면 초기화된다는 것이다. Anthropic은 이를 교대 근무제로 운영되는 소프트웨어 팀에 비유했다. 새 엔지니어가 출근할 때마다 이전 교대 근무 중 어떤 일이 있었는지 아무것도 기억하지 못한 채로 일을 시작하는 상황이다.
솔로 개발자들에게 이것은 일상적인 좌절감이다. 전날 밤 Claude와 함께 어떤 아키텍처 결정을 내리고, 어떤 파일을 수정했는지 합의를 마쳤는데, 다음 날 세션을 열면 Claude는 무작위로 파일을 탐색하며 엉뚱한 방향으로 작업을 시작한다. 개발자는 이미 결정된 사항들을 다시 설명해야 한다. 이 반복되는 재설명 작업이 Claude Code 워크플로에서 가장 큰 시간 낭비라고 Daniel은 지적한다.
Anthropic의 해결책: 초기화 에이전트 + 진행 상황 파일
Anthropic은 이 문제를 두 가지 역할을 분리한 에이전트 구조로 해결했다.
초기화 에이전트(Initializer Agent): 첫 번째 세션에서만 실행된다. 이 에이전트의 역할은 환경을 세팅하는 것이다. 구체적으로는
init.sh스크립트를 작성하고, 진행 상황 추적 파일(claude-progress.txt)을 생성하며, 첫 번째 git 커밋을 남긴다.코딩 에이전트(Coding Agent): 이후 모든 세션에서 실행된다. 새 세션이 시작될 때 이 에이전트는 진행 상황 파일을 읽고, git 히스토리를 확인하여 현재 프로젝트의 상태를 즉시 파악한다. 추측이나 탐색 없이 바로 작업을 이어갈 수 있다.
커뮤니티와의 연결: CLAUDE.md와 progress.md
Daniel은 이 구조가 솔로 개발자 커뮤니티에서 독립적으로 발전해 온 하네스 엔지니어링(harness engineering) 패턴과 거의 동일하다는 점을 강조한다.
CLAUDE.md: 아키텍처 문서, 코딩 규칙, 의사결정 기록을 담는 파일. 새 세션이 시작될 때 Claude가 가장 먼저 읽는 파일이다.progress.md: 완료된 작업, 진행 중인 작업, 다음에 해야 할 작업을 추적하는 파일.
Anthropic의 초기화 에이전트가 하는 일과 CLAUDE.md + progress.md 조합이 하는 일은 같은 원리, 같은 결과다. 모델 자체가 답이 아니라, 모델을 감싸는 하네스(harness)가 답이라는 것이 핵심 교훈이다.
2. 원샷 과부하 (One-Shotting the Entire Project)
문제: Claude는 모든 것을 한 번에 하려고 한다
두 번째 실패 패턴은 에이전트가 큰 기능 요청을 받았을 때 프로젝트 전체를 한 번에 구현하려는 경향이다. 개발자가 간단한 기능 하나를 요청했는데, Claude가 다음과 같은 행동을 한다.
- 요청하지 않은 파일들을 재구성한다.
- 요청하지 않은 기능들을 추가한다.
- 컨텍스트 한계에 도달할 때까지 “영웅적인” 구현을 시도한다.
- 컨텍스트가 소진되면 구현이 절반쯤 완료된 상태로 멈춘다.
- 다음 세션에서 새 에이전트가 이 어중간한 상태를 정리하느라 컨텍스트를 낭비한다.
Anthropic은 Opus 4.5로도 동일한 문제를 경험했다고 밝혔다. “claude.ai 클론을 만들어라”라는 고수준 프롬프트만 주었더니, 에이전트가 앱 전체를 원샷으로 구현하려다 컨텍스트 중간에 멈춰버렸고, 다음 세션의 에이전트가 상황을 파악조차 하지 못하는 리포지토리 상태가 되었다.
Anthropic의 해결책: JSON 형식의 기능 목록 파일
Anthropic의 해결책은 놀라울 만큼 단순하다. JSON 형식의 기능 명세 파일을 만들고, 에이전트는 한 번에 하나의 기능만 처리하도록 강제하는 것이다.
1
2
3
4
5
6
7
{
"features": [
{ "name": "사용자 로그인", "passes": false },
{ "name": "대시보드 렌더링", "passes": false },
{ "name": "알림 시스템", "passes": false }
]
}
초기화 에이전트가 이 파일을 생성하고, 모든 기능의 초기 상태를 false로 설정한다. 코딩 에이전트는 목록에서 하나를 선택하고, 구현하고, 커밋하고, passes 값을 true로 업데이트한 뒤 다음 기능으로 넘어간다.
왜 JSON인가: 파일 형식이 에이전트 제어 수단이 된다
Daniel이 특히 흥미롭다고 언급한 부분은 왜 마크다운이 아닌 JSON을 선택했는가다. 마크다운 체크리스트를 사용하면 Claude는 목록 전체를 재구성하거나 새 항목을 추가하거나 형식을 바꾸려는 시도를 한다. 반면 JSON을 사용하면 Claude는 더 신중하게 처리하며, 지정된 필드(passes)만 수정하고 나머지 구조는 그대로 유지하는 경향이 있다.
이 발견은 더 넓은 원칙을 제시한다. 파일 형식 자체가 에이전트 동작을 제어하는 수단이 될 수 있다는 것이다. 리포지토리 문서 구조를 설계할 때 단순히 내용뿐만 아니라 형식도 전략적으로 선택해야 한다는 새로운 관점이다.
3. 섣부른 완료 선언 (Premature Victory / Saying It’s Done When It’s Not)
문제: 에이전트는 완료되지 않은 작업을 완료했다고 한다
세 번째 실패 패턴은 신뢰의 문제다. 에이전트가 자신 있게 “완료됨”이라고 선언하고 구현 내용을 요약하는 메시지를 작성하지만, 실제로 테스트하면 기능이 작동하지 않거나 절반만 작동하거나 엣지 케이스에서 무너진다.
Anthropic은 명시적인 종단간 테스트 지시 없이 Claude가 어떻게 동작하는지 관찰했다. Claude는 다음과 같은 절차를 따랐다.
- 코드를 변경한다.
- 유닛 테스트를 실행한다.
- 개발 서버에 curl 명령을 날려
200 OK응답을 받는다. - “기능 완료”를 선언한다.
그러나 실제 사용자 관점의 경험은 망가진 상태였다. 에이전트는 실제 인간이 앱을 사용하는 방식으로 테스트하지 않았기 때문에, 자신의 실패를 인식하지 못했다.
Anthropic의 해결책 1: 브라우저 자동화 (Puppeteer + MCP)
Anthropic은 Puppeteer를 MCP(Model Context Protocol) 서버로 연결하여 Claude에게 진짜 사람처럼 테스트하도록 지시했다. “브라우저를 열어라. 버튼을 클릭해라. 폼을 채워라. 실제로 화면에 무엇이 보이는지 확인해라.” 이 접근법으로 테스트 결과의 질이 극적으로 향상되었다고 Anthropic은 밝혔다.
네이티브 앱(iOS/Android) 개발자에 대한 과제: Daniel은 이 지점에서 솔직한 한계를 인정한다. 웹 앱에는 Puppeteer가 있지만, SwiftUI 같은 네이티브 iOS 앱에는 동등한 자동화 도구가 없다. Xcode MCP로 빌드 로그와 프리뷰를 확인할 수는 있지만, 실제 사용자 흐름을 시뮬레이션하는 종단간 테스트는 여전히 미해결 과제로 남아 있다.
Anthropic의 해결책 2: 강력하고 명확한 지시문
두 번째 해결책은 프롬프트 작성 방식의 변화다. Anthropic은 다음과 같은 비타협적인 언어를 사용했다.
“테스트를 삭제하거나 수정하는 것은 절대 허용되지 않는다.”
(“It is unacceptable to remove or edit tests.”)
Daniel은 대부분의 솔로 개발자들이 에이전트에게 지나치게 정중하게 지시문을 작성한다고 지적한다.
“가능하다면 테스트 파일을 수정하지 않도록 해주세요.”
이런 표현을 보면 Claude는 “테스트가 잘못되었다”는 이유를 스스로 찾아내고 테스트를 수정해버린다. 하지만 절대적이고 협상 불가능한 언어를 사용하면, 모델은 이를 단순한 제안이 아닌 넘을 수 없는 벽으로 인식한다는 것이다.
물론 이에 대한 트레이드오프도 있다. 지시문이 너무 엄격하면 에이전트가 실제로 테스트가 잘못된 경우에도 적응하지 못할 수 있다. Daniel은 완벽한 답을 갖고 있지 않지만, 에이전트가 자신의 성공 기준을 스스로 재작성하는 것보다는 지나치게 엄격한 편이 낫다고 결론을 내렸다.
핵심 교훈: 모델이 아니라 하네스가 답이다
영상의 가장 중요한 메시지는 다음 한 문장으로 요약된다.
“The model is not the fix. The harness around the model is the fix.”
(모델이 해결책이 아니다. 모델을 감싸는 하네스가 해결책이다.)
Anthropic의 실험과 커뮤니티 개발자들의 독립적인 실천이 동일한 결론에 도달했다는 사실은 매우 의미심장하다. 최고 성능의 모델을 사용하더라도 다음과 같은 외부 구조 없이는 장기 프로젝트에서 신뢰할 수 있는 결과를 얻을 수 없다.
| 문제 | 해결책 |
|---|---|
| 세션 간 컨텍스트 소실 | 진행 상황 파일 (progress.md / claude-progress.txt) + git 히스토리 |
| 원샷 과부하 | JSON 기능 목록 파일 + 점진적 진행 강제 |
| 섣부른 완료 선언 | 브라우저 자동화 테스트 + 강력한 비협상적 지시문 |
AI 에이전트 파일 형식 선택 가이드
이 영상에서 파생된 실용적인 인사이트를 정리하면 다음과 같다.
- JSON 파일: 에이전트가 특정 필드만 업데이트해야 하는 구조화된 상태 데이터에 적합. Claude가 임의로 재구성하지 않는다.
- 마크다운 파일 (CLAUDE.md 등): 아키텍처 결정, 규칙, 컨텍스트 전달 목적. 에이전트가 읽고 따르도록 설계.
- 텍스트 파일 (progress.txt 등): 자유 형식의 진행 상황 기록. 세션 핸드오프 목적.
- git 히스토리: 코드 변경의 타임라인. 에이전트가 “무엇이 변경되었는가”를 파악하는 가장 신뢰할 수 있는 소스.
Anthropic 엔지니어링 블로그 원문 핵심 인용
Anthropic의 공식 블로그에 따르면, 이 접근법에 대한 영감은 다음에서 비롯되었다.
“효과적인 소프트웨어 엔지니어들이 매일 하는 일에서 영감을 받았다.”
컨텍스트 윈도우가 제한되어 있고 복잡한 프로젝트의 대부분은 단일 컨텍스트 윈도우 안에서 완성될 수 없으므로, 에이전트는 코딩 세션 사이의 간격을 메울 방법이 필요하다는 것이 핵심 전제다.
결론: 솔로 개발자에 대한 검증
이 영상이 솔로 AI 개발자 커뮤니티에서 반향을 일으킨 이유는 단순하다. Anthropic이 자신들도 동일한 문제를 겪었고, 해결책이 모델 업그레이드가 아닌 파일, 진행 상황 추적, git 히스토리, 명시적 테스트, 단호한 지시문이었다고 공개적으로 인정했기 때문이다.
CLAUDE.md와 progress.md 같은 파일을 만들고 세션 핸드오프 시스템을 구축하는 것이 과도한 복잡성처럼 느껴졌다면, 이제 그렇지 않다는 공식적인 확인을 받은 것이다. 당신은 과하게 복잡하게 만든 것이 아니다. Anthropic도 똑같이 해야 했다.