요즘 AI 에이전트랑 하루종일 같이 일한다.
\n회사 일도, 사이드 도 대부분 Claude Code 를 옆에 띄워두고 같이 진행한다.
코드 생성에만 쓰는건 아니다.
\nPR 리뷰, 디버깅, 리팩토링, 문서 정리까지 웬만한건 다 같이 한다.
\n편하긴 정말 편한데, 그냥 풀어놓으면 큰 화를 면치 못할것이다.\n타입 에러를 고치라니 any 로 때려버리고,(요즘엔 거의 없다..)
\n실패하는 테스트를 고치라니 테스트 자체를 지워버리고,
\n리팩토링을 하라니 멀쩡한 로직을 잘라먹고.
최근에는 모델들이 다을 우수해서인지 이제 기초적인 실수는 안하긴 한다.
\n요즘은 프롬프트만 열심히 짜는 게 아니라,
\n이 녀석들이 일하는 환경 자체를 설계하는 데 더 많은 시간을 더 써야 하는건
\n누구나 알 것이다.
흔히 말하는 하네스 엔지니어링(Harness Engineering) 이다.
\n개념 자체는 단순하다.
\nAI 에이전트가 보는 컨텍스트, 쓸 수 있는 도구, 권한, 실행 흐름 같은
\nAI 주변의 런타임 전체를 설계하는 일이다.
\n프롬프트가 무엇을 시킬지 라면, 하네스는 어디서 어떻게 일하게 할지 에 가깝다.
개념 설명보다 내가 실제로 뭘 해보고 어떻게 좋아졌는지가 더 쓸모 있을 것 같다.
\n최근 작업 중인 사이드 프로젝트에서 이렇게 세팅했더니 체감이 꽤 좋았다.
docs/ 와 .agent/ 를 연결하기프로젝트 루트에 문서와 에이전트 설정을 따로 두었다.
\ndocs/ — 기능별 명세, 가이드라인, 테스트 전략 등 사람이 읽는 문서docs/HARNESS.md — 기능 ↔ 문서 ↔ 코드 매핑표 (진입점)docs/features/*.md — 기능별 상세 (관련 파일, DB 스키마, 로직, 테스트).agent/ — 에이전트 전용 지침 (rules, skills, workflows, pipeline).claude/ — Claude Code 전용 설정 (rules, skills)CLAUDE.md — 루트 진입점. 위 문서들로 가는 포인터만 얕게 둔다핵심은 CLAUDE.md 를 얕게 유지 하는 부분이다.
\n기능 작업 전 반드시 docs/features/<feature>.md 를 먼저 읽어라 정도의 라우팅 지침만 넣고,
\n실제 도메인 지식은 docs/features/ 쪽에 분산시켜 두었다.
\n처음부터 모든 문서를 컨텍스트에 박지 않고, 필요할 때 해당 문서만 읽어오게 하는 방식이다.
이건 Anthropic 이 말하는
\nJust-in-time context loading 과 같은 개념인데,
\n직접 해보니 컨텍스트 낭비가 확연히 줄기는 줄어든 것 같다.
\n아마도…🤔
전역 CLAUDE.md 에 모든 규칙을 다 때려넣는 대신,
\n역할이 명확한 작업은 슬래시 커맨드(.claude/skills/) 로 분리했다.
| Skill | \n용도 | \n
|---|---|
/git-push | \n커밋 컨벤션 + 푸시 절차 | \n
/i18n | \n다국어 (ko.json / en.json 동시 업데이트) | \n
/tdd | \n테스트 주도 개발 루프 | \n
/pipeline | \nPlan → Execute → Verify 3-Agent 자동화 | \n
/pr-analyzer | \nPR 리뷰 체크리스트 | \n
이 외에 추가적인 많은 기능들 등등.
\n이렇게 분리해두면 해당 작업을 할 때만 관련 지침이 컨텍스트에 로드된다.
\ni18n 작업 중에 DB 마이그레이션 규칙을 컨텍스트에 들고 있을 이유가 없기 때문이다
커밋 직전과 세션 종료 시 자동으로
\ntsc --noEmit, eslint, test 를 돌리도록 hook 을 걸어두었다.
\nAI 가 테스트 통과했습니다 라고 말하는 걸 곧이곧대로 믿지 않기 위함이다.
\n통과했다 는 주장과 실제 통과 여부가 꽤 자주 어긋난다.\n요즘들어 더 심해진듯? 🤔
이렇게 세팅한 뒤로, 세션 하나에 매번 반복해서 넣어야 하는 맥락이 확실히 줄었다.
\n내가 같은 주의사항을 말해주는 일도 줄었고,
\n이 기능 건드릴때 어떤 파일 봐야 해? 같은 예비 질문도 거의 사라졌다.
하네스를 아무리 잘 설계해도 결국 AI 가 보는 건 컨텍스트다.
\n여기가 망가지면 다른건 의미가 없다.
처음엔 Claude 의 윈도우가 200k, 1M 까지 나왔으니
\n웬만하면 꽉 채워 써도 괜찮을 거라고 생각했다.
\n현실은 정반대였다.
Stanford 의 Lost in the Middle (Liu et al., 2023) 은
\n20개 문서(약 4,000 토큰) 만 넣어도 답변 정확도가
\n70~75% 에서 55~60% 로 떨어진다는 걸 실험으로 보였다.
\n생각보다 훅 떨어진다. 🙃
\n정답이 컨텍스트 맨 앞이나 맨 뒤에 있을 때 정확도가 가장 높고,
\n중간으로 갈수록 놓치는 U 자 커브 가 관찰된다.
원인은 단순히 토큰 수 초과 가 아니다.
\nAttention 가중치가 전체 컨텍스트에 분산되기 때문에,
\n입력이 길어질수록 특정 위치의 정보에 집중하기 어려워진다.
\n용량의 문제가 아니라 구조적인 한계에 가깝다.
\n결국 얘네도 집중력 총량이 정해져 있는 셈이다.
\n사람이랑 똑같네…
Chroma 의 2025년 Context Rot 연구는 이걸 더 넓게 보여준다.
\nGPT-4.1, Claude 4, Gemini 2.5, Qwen3 등 18개 프런티어 모델을 테스트했는데,
\n단순 retrieval 이나 텍스트 복제 같은 기초 과제에서도
\n입력 토큰이 길어질수록 예외 없이 성능이 떨어졌다.
\n잘난 모델들 다 모아놨는데 하나같이 긴 컨텍스트 앞에서는 헤매더라는 얘기. 🤡
\n쿼리와 정답의 의미적 유사도가 낮을수록 하락 속도가 더 가팔라진다.
요약하면, 긴 컨텍스트 윈도우가 있다는 것과
\n그 길이만큼 품질이 유지된다는건 다른 얘기다.
\n실제 제품에서는 한참 전에 품질이 깎여 나가기 시작한다.
\n머리는 좋은데 건망증이 심한 친구랄까? 🙃 좀 이상한데..
Claude Code 에서는 대략 이렇게 쓰고 있다.
\n20 ~ 30% 사이에서 /clear10% 넘기기 전에 /clear숫자 자체보다 중요한 건 꽉 차기 전에 비운다 쪽이다.
\n위 연구들이 시사하는 건 한계치 근처에서 버티면 품질이 이미 깎이고 있다 이기 때문에
\n여유있게 끊어주는게 결과적으로 더 낫다.
클리어 하기 직전에는 중요한 결정이나 맥락을
\nCLAUDE.md, memory, handoff 파일로 내려두고,
\n다음 세션에서 필요한 것만 다시 읽게 한다.
\nAnthropic 공식 가이드도
\nunrelated task 사이에는 공격적으로 /clear 를 써라 를 권장한다.
\n한 세션에 무관한 주제 여러개를 이어가면 누적된 오해가 이후 판단을 흐리게 된다.
이건 사람한테 일 시킬 때랑 똑같은 얘기다.
\n한번에 10개를 다 해달라고 하면 반드시 어딘가는 부실하다.
나는 보통 이런 단위로 쪼개서 세션을 구분한다.
\n한 세션 한 관심사 정도로 유지하면 컨텍스트도 가볍고,
\n중간에 방향이 틀어졌을 때 되돌리기도 쉽다.
\n덤으로 내가 뇌를 비우고 🤡 AI 에 끌려다니는 것도 방지된다.
Claude 하나에만 의존하지 않는 것도 같은 맥락이다.
\n설계, 리뷰, 리팩토링은 Claude 위주로 쓰고,
\n최신 문서나 레퍼런스 조사는 Gemini, 다른 관점이 필요할때는 ChatGPT 를 섞는다.
이게 왜 효과가 있는지도 최근 연구들이 설명해준다.
\nSelf-consistency 는 같은 모델의 여러 샘플을 모아 다수결을 내는 기법인데,
\nComplementing Self-Consistency with Cross-Model Disagreement 는
\n이 방식의 한계를 지적한다.
모델이 틀린 답에 과도한 확신을 가지는 경우,
\n같은 모델을 여러 번 샘플링해도 똑같이 틀린 답이 반복된다.
\n자기 의심이 없는 모델의 다수결은 틀린 방향을 강화할 뿐이다.
\n목소리 큰 애들 여럿 모아봐야 틀린건 여전히 틀리다는 얘기다. 🤡
반면 서로 다른 학습 데이터와 구조를 가진 모델들에게 같은 질문을 던지면,
\n한쪽이 overconfident 하게 틀리는 경우에도 다른 쪽이 불일치를 보일 가능성이 높다.
이 cross-model disagreement 가 여기 뭔가 이상하다 는 신호가 된다.
\n불확실성을 정량화하는 지표로도 self-consistency 단독보다 더 잘 작동한다는게 해당 연구의 요지다.
실제로 써보면 서로의 약점을 신기할 정도로 잘 잡아낸다.
\nClaude 가 놓친 엣지 케이스를 Gemini 가 짚어주고,
\nGemini 가 어색하게 쓴 타입 정의를 Claude 가 다듬는 식이다.\n은근히 싸움 붙여놓는 재미도 있다. 🤔
한 모델의 편향을 덜 받는 것만으로도 의사 결정 품질이 눈에 띄게 올라간다.
\n중요한 설계 결정이나 보안 판단은 한 녀석에게만 맡기지 않는 쪽이 안전하다.
\n크로스 체크와 비슷한 아이디어를 한 모델 안에서 적용한 게
\n요즘 쓰고 있는 3-Agent 파이프라인이다.
plan.md 에 적힌 대로만 구현. 계획에 없는건 하지 않음세 에이전트는 각각 다른 세션(채팅) 에서 돌고,
\nhandoff/ 폴더의 파일을 통해서만 소통한다.
\n내 프로젝트에서는 이런 식으로 배치돼 있다.
.claude/skills/pipeline/\n├── SKILL.md\n├── agents/\n│ ├── planner.md\n│ ├── executor.md\n│ └── verifier.md\n└── handoff/\n ├── plan.md\n ├── execution-log.md\n └── verification.md\n 각 에이전트 지침에는 역할 제한을 명확히 박아둔다.
\n## 역할 제한 (Plan Agent Boundaries)\n\n- 코드 수정 금지: `.ts`, `.tsx`, `.css`, `.json` 등\n- 상태를 변경하는 명령 실행 금지 (`pnpm`, `git commit` 등)\n- 허용: 파일 읽기, 디렉토리 탐색, 웹 검색, handoff 파일 작성\n Verify 쪽도 비슷하게 문제를 발견해도 코드를 고치지 말고 verification 파일에만 적어라 를 강제한다.
\n재시도 루프가 돌 때 Plan 이 이 verification 파일을 읽고 계획을 새로 세운다.
verification.md 를 들고 Plan 을 다시 세우면 된다.plan.md 가 부실하면 Execute 가 엉뚱한 걸 만든다.문서로 정확히 소통하는 능력 이 이 방식의 병목이다.설계 결정이 중요한 작업, 리팩토링, 기능 추가처럼
\n적당히 큰 단위에서 이 방식이 빛을 발한다.
\n버그 픽스나 스타일 수정 같은 단발성 작업은 한 세션에서 처리하는 편이 빠르다.
정리하면 요즘 지키려는 규칙은 이렇다.
\ndocs/features/ 로 밀어내 필요할때만 로드한다/clear 에 인색하지 말자완벽한 방법은 당연히 아니다.
\n계속 써보고 바꾸고 있다.
\n결과물이 눈에 띄게 안정적인건 확실하다.
애초에 개발자라면 바이브 코딩을 하면 할수록 이거 해줘 만으로는
\n어림도 없다는걸 알게 된다.
\n초기에도 그랬고 현재까지도 그렇다.
미래는 모르겠다.
\nAnthropic 의 Mythos? 어마 무시해서 일반인에게 공개를 안한다고 하는데
\n저런 공포 마케팅을 너무 많이 봐서 아직은 믿음이 안간다..
\nAnthropic IPO 가 얼마 안남기도 했고. 🤡
쨌든 AI 를 잘 쓰는 일이 결국 AI 를 어떻게 가둬둘 것인가의 문제라는게
\n써볼수록 점점 더 명확해진다. 🥹