1년 가까이 Claude Code로 작업하면서, 처음에는 프롬프트를 잘 쓰는 데 집중했고 그다음엔 컨텍스트를 잘 만드는 데 집중했습니다.
그런데 지금 돌아보니, 에이전트가 일하는 환경을 설계하는 일이 가장 중요한 것 같습니다.
환경을 어떻게 구성하면 에이전트가 더 잘 일하는지를 4가지 장치로 정리한 노트입니다.
개요: 환경을 고치면 결과가 바뀐다
에이전트가 같은 실수를 반복할 때, 결과물을 사람이 고치는 건 초보적인 단계이며, 지속 가능하지 않습니다. 왜냐하면 ai에이전트의 생산속도는 우리가 리뷰하고 고치는 속도를 이미 뛰어넘었기 떄문입니다.
오히려 에이전트에게 같은 실수를 다시 못 하도록 환경을 고치는 게 현재 단계에서 가장 효과적인 전략입니다.
물론, 다음 주만 되어도 이 전략이 구식이 될 수도 있습니다(그러길 바래요!)
1년 정도 에이전트로 일해본 현재 단계에서 여기저기 귀동냥 하고 공부하며 어떻게 구성하면 에이전트가 더 잘 일하는지를 제 기준으로 정리한 노트입니다.
메모리 룰, Don'ts 룰을 비롯해서 여러 내/외부 도구를 운영하면서 만든 팁을 4가지 카테고리로 풀어봤습니다.
4가지 장치 분류(Commands/Rules/Skills/Hooks)는 Anthropic의 Harness design for long-running apps 자료와 교차 검증해 정리했습니다.
이미 이전에 제 velog에 작성한 에이전트 폭주 방지, 페르소나의 한계, 살아남은 Skill 5종 등 포스팅을 통해 공유한 팁의 총합본 같은 느낌입니다.
1. 프롬프트 < 컨텍스트 < "환경"
필드에 있으면서 느낀 AI 엔지니어링의 무게중심은 이렇게 옮겨온 것 같습니다.
(더 빨리 옮겨졌을 수 있음!)
| 단계 | 시기(대략) | 핵심 질문 | 대표 기술 |
|---|---|---|---|
| 프롬프트 엔지니어링 | 2022~23 | "무엇을 물어볼까?" | CoT, Few-shot |
| 컨텍스트 엔지니어링 | 2024~25 | "무엇을 보여줄까?" | RAG, MCP, long-context |
| 환경 엔지니어링 | 2026~ | "어떤 환경에서 일하게 할까?" | Rules, Hooks, Skills, Commands, Subagents |
프롬프트와 컨텍스트는 휘발성입니다. 세션이 끝나면 사라집니다. 반면 환경 설계는 리포지토리에 남는 자산입니다.
이게 무게중심 이동의 핵심 분기점입니다.
다음 호출에서도 살아남는 것을 만들기 위해서 기술도 발전하고, 기술을 사용하는 개발자들도 같이 발전한 것 같아요.
2. 1년 운영하면서 굳어진 결론 세 가지
Flutter APP, SAAS web, Unity 게임, React + Supabase 웹앱 등을 포함해 여러 프로젝트를 매니징 해주고, 그 외에도 내가 귀찮아 하고 어려워 하는 마케팅·기획·CS·책 노트·요리까지 묶은 허브 리포지토리(나는 ideaBank라고 부르고, 다른 사람에게는 자비스라고 소개중)를 동시에 굴리면서 1년을 보냈습니다.
도메인이 전혀 다른데도 같은 실수가 다른 모습으로 반복되더군요 — Unity 퀘스트 가드 누락이나 React 컴포넌트 prop drilling이나, 결국은 "에이전트가 같은 패턴을 다시 만들고 있는데 이걸 막을 룰이 없다"는 한 가지 문제로 수렴했습니다.
룰을 어디에 어떻게 쌓느냐에서 나온다는 게 보였습니다.
이 시행착오를 압축하면, 제 개발 기록을 통해서는 3가지 정도 팁을 얻을 수 있습니다.
1. 에이전트의 실수는 코드의 문제가 아니라 환경 설계의 미비다.
- 에이전트가 실수했을 때 결과물을 사람이 고치는 건 하수. 에이전트가 다시는 그 실수를 못 하도록 규칙·검증·훅을 수정하는 게 고수라고 개발자 선배가 그러더라구요?
- 예를 들어 개발중인 게임에서 퀘스트 보상이 두 번 지급되는 버그를 잡았을 때, 코드만 고치고 끝낸 게 아니라 "퀘스트 조건 체크 시
isCompleting가드 필수"를 룰로 승격시킵니다. - 이러면 어떤 모델과 일하는 지는 상관없이, 다음 작업에서는 자동으로 막힙니다.
이걸donts.md와feedback_*.md메모리 파일에 꼼꼼히 기재하도록 규칙을 세워 꾸준히 실수 패턴을 축적해보니 확실히 개선되는게 보였습니다(같은 실수를 두 번 보면 룰로 승격시킨다는 단순한 원칙입니다)
2. 자율성과 통제는 반비례가 아니라 정비례다.
- 모델이 똑똑해질수록 runaway(통제 불능) 위험도 같이 커집니다.
다행히 전 그런 일이 없었는데, 모델이 마음대로 마케팅 강의를 결제하거나 하는 등 폭주한 사례는 이미 유명하죠?! - 앞서서 "폭주 방지"에 대한 velog글도 썼는데, 그것도 여기서 출발했습니다.
"적합한" 통제 장치가 잘 세팅되면 더 큰 작업을 안전하게 맡길 수 있습니다. 하네스 엔지니어링이라고 부르죠 이젠?!
3. 개발자는 코드를 짜는 사람이 아니라, AI가 코드를 잘 짤 수 있는 환경을 짓는 건축가다.
- 손으로 친 코드 라인 수보다, 에이전트가 잘 작동하도록 만든 룰·훅·도구의 코드 라인이 이제 비교할 수 없을 만큼 깁니다.
우리는 "AI-native 개발자 / Harness Engineer"가 되기 위해 노력하고,
개발을 잘 기획하는 사람이 되기 위해 노력해야 하는 시대가 되었다고 생각합니다.
3. Claude 사용 환경을 구성하는 4가지 장치
환경을 구성하는 4개의 카테고리입니다. 각 장치가 어떤 역할을 하는지, 제 시스템에서 어떻게 작동하는지 매핑해봤습니다.
| 장치 | 정의 | 제 시스템에서 |
|---|---|---|
| Commands | 반복 작업의 진입점 (슬래시 커맨드) | /검수, /loop, /critic 등 — 이 글에서 정리 |
| Rules | 상시 주입되는 규약 | CLAUDE.md, .claude/rules/ 전체 (프로젝트별 + 카테고리별 분리) |
| Skills | 에이전트가 호출하는 외부 능력 | tools/ 하위 25+ 스크립트 (gemini-cli, hatchet-art, design-report…) |
| Hooks | 이벤트 기반 강제 검증/자동화 | Stop hook(자동 커밋), UserPromptSubmit(키워드 라우팅) 등 |
각 장치는 다른 조건을 책임집니다. Commands는 반복 진입의 일관성, Rules는 상시 판단의 기준, Skills는 확장된 능력, Hooks는 이벤트 기반 강제력. 4개가 한 세트로 갖춰지면 에이전트가 같은 작업에서 매번 같은 품질을 내고, 같은 실수를 반복하지 않으며, 사람이 일일이 검토하지 않아도 결과물이 안정됩니다.
하나라도 비면 다른 쪽에 부담이 쏠립니다. 예를 들어 Hook이 약하면 Rules에 "이건 하지 마세요"를 10배 적어야 해서 컨텍스트 예산만 잡아먹습니다. Skills가 빈약하면 같은 작업을 매번 프롬프트로 풀어 설명하느라 토큰을 낭비합니다.
4. 4가지 장치로 본 제 시스템의 약한 지점
잘 갖춰진 영역은 3부작에서 이미 써봤으니, 이번엔 비어 있는 쪽에 집중해봤습니다.
*Claude가 분석해주었습니다
| 약점 | 증거 | 개선 방향 |
|---|---|---|
| Hook 커버리지 부족 | Stop hook(자동 커밋)은 있지만, 작업 완료 전 검증을 강제하는 훅은 없음 | PostToolUse/Stop 훅에 /검수 code 자동 트리거 조건 추가 |
| 규칙 드리프트 | feedback_*.md가 30개 이상으로 누적, 일부가 .claude/rules/로 승격 안 됨 | 분기마다 메모리 → rules 승격 감사 프로세스 |
| Handoff 규격 부재 | Designer → Implementer 전달물이 자유형 텍스트라 포맷이 들쭉날쭉 | 구현 계획서 템플릿(파일/함수 수준) + YAML frontmatter 메타 |
| Harness Audit 부재 | 모델이 업그레이드됐을 때 기존 규칙이 여전히 유효한지 재검토하는 절차가 없음 | audit-harness.sh — 컨텍스트 사이즈, 규칙 중복, 실효성 체크 |
| 실수 패턴 룰화 지연 | 병렬 에이전트 경계, 퀘스트 가드 등 실전 교훈이 메모리에만 있음 | "Don'ts" 룰 파일로 명문화 (일부는 이미 진행 중) |
이 표를 만들고 보니, 제 시스템은 Commands와 Rules는 촘촘한데, Hooks와 감사 루틴이 얇다는 비대칭이 있었습니다. 다음에 손봐야 할 우선순위가 여기서 나옵니다.
5. 약점을 어떻게 메우고 있나
5.1 보안 스캔으로 Hook 커버리지 보완
현재 제가 쓰는 ideaBank 프로젝트엔 9개의 커스텀 에이전트 + 다수 hook + MCP 서버 7개(Context7, PixelLab, Notion 등) + 권한관련 설정(settings.json)이 있습니다.
그런데 가장 문제가 이 환경 자체를 정기 검사하는 수단이 없었습니다.
뭘 더 좋아지게 만드려면 혹은 사고치는걸 막으려면 제대로 검사를 해야하는데.. 에이전트 정의에 시크릿이 흘렀는지, hook에 명령 주입 여지가 있는지, MCP 권한이 과한지 점검할 도구 자체가 없어서 고민이 좀 있었습니다.
Everything Claude Code 레포의 security-scan 스킬(AgentShield, 1282 tests / 102 rules)을 한 번 돌렸습니다. 결과:
- 위험 명령 차단을 위한 deny list 보강
- 자동 커밋 hook이 토큰을 흘릴 수 있는 경로를 잡아 시크릿 필터 + 로테이션
- 노출 가능성 있는 Vercel 토큰 회수
Hook 자체가 두꺼워진 건 아니지만, 기존 Hook의 약한 지점을 데이터로 본 것만으로도 다음 보강 우선순위가 명확해졌습니다.
5.2 실수 패턴 방지 제도
(4번 표에선 두 약점으로 나눴지만 결국 같은 결의 문제 — 룰을 어떻게 쌓고 어떻게 승격시키느냐. 처방을 묶어서 다룹니다)
feedback_*.md 메모리가 30+개로 누적되는데 일부만 정식 룰로 승격되는 게 가장 큰 문제였습니다. 그래서 두 가지 절차를 박았습니다.
(1) 삼진아웃 제도 — 같은 패턴이 몇 번 반복되면 룰로 올리는지 명시:
| 발생 횟수 | 조치 |
|---|---|
| 1회 | 메모리에만 저장 |
| 2회 | donts-audit.md에 "승격 후보" 플래그 |
| 3회 | donts.md 또는 donts/{기능}.md에 정식 룰 등록 |
(2( 기능별 Don'ts 분리:
실수를 반복하지 않는 체계를 구축합니다.
그리고 파일에 다 쌓으면 컨텍스트 부담이 커지니 아래처럼 분기해두면 좋습니다.
donts.md— 전역 (모든 작업 공통)donts/game.md— 게임/Unity 개발donts/someProject.md— 특정 프로젝트 개발donts/marketing.md— 마케팅/콘텐츠 아티클 발행 및 수정donts/images.md— 이미지/에셋
이젠 작업 진입 시 해당 파일만 로드하니 평소 컨텍스트가 가벼워졌습니다.
룰화 자체를 더 자동화하는 건 ECC /learn 패턴 시범 검토 중.
5.3 컨텍스트 예산 진단(Harness Audit 부재관련)
/context-budget을 한 번 돌려서 토큰 분포를 봤더니 매 세션 강제 로드는 ~3%로 양호했습니다. 그런데 부수 발견이 더 컸어요 — 마케팅 에이전트 3개(brand-manager, content-adapter, marketing-director)에 YAML frontmatter가 누락돼 있어 Claude Code가 자동 매칭으로 호출하지 못하는 상태였습니다. 진단한 같은 날 3개 모두 frontmatter 추가해 정상화.
진단 도구 한 번 돌리는 게 잠재 결함을 수면 위로 끌어올렸습니다. 정기 감사 루틴까진 아직이지만, 진단의 ROI는 확인됐어요.
5.4 포매터 강제 (Handoff 규격)
Designer → Implementer 전달물이 자유형 텍스트라 포맷이 들쭉날쭉한 문제는 에이전트 효율을 위해 중요한 문제라고 하더라구요.
그래서 이를 VLM 추론 결과 처리를 공부하며 3단 안전장치를 설계하고 적용하고 있습니다.
(이전 글에 작성한 내용입니다.)
① 모델에 JSON 응답 모드 강제(responseMimeType: 'application/json'),
② 정규식으로 첫 {...} 블록만 추출(prose/펜스 섞여 와도 잡힘),
③ JSON.parse + 스키마 검증(필수 필드/타입 안 맞으면 명확한 에러로 차단).
이 패턴을 공부하며 ideaBank등 기존 프로젝트들에도 적용하려고 합니다.
이를 통해서 Designer에이전트가 Implementer에게 핸드오프 할 떄 효율을 올려볼 계획입니다.
정리: 환경을 개발하는 것이 자산이 되는 이유
모델을 믿지 말고, 모델이 최고 성능을 낼 수밖에 없는 환경을 만들어봅시다.
모델은 비정기적으로 바뀝니다. 그래도 잘 구축한 환경(Commands, Rules, Skills, Hooks)은 다음 모델에서도 그대로 살아남을 확률이 높습니다. 새 모델이 나왔을 때 개선점만 집어넣고, 처음부터 다시 시작하지 않아도 됩니다.
안그래도 최근에 Opus의 버전업과 동시에 Claude쪽에 이슈가 있었다는 개발자님들이 의견이 많이 보였습니다.
이러한 시행착오의 노트가 도움이 되기 바랍니다.
참고 자료
