발행 순서와 읽는 순서는 다르다 — 30편 지도와 15주제 교차 참조
이 카테고리의 30편을 두 번 갠다 — 발행 구조 그대로인 8개 시리즈와 독립편 2로 한 번, 깊이 순서의 15개 주제로 다시 한 번. 목적별 읽는 순서 여덟 갈래를 함께 놓고, 두 지도 어느 쪽에서도 빠지는 편이 없는지 자리를 세어 확인한다.
에이전틱 코딩
Claude Code로 짓는 개발 워크플로 — 컨텍스트 엔지니어링, MCP·Skills·Hooks, 멀티에이전트
31편
7원칙의 자리는 그대로고 내용만 업종을 탄다 — CLAUDE.md 템플릿 3종 10축 비교
1인 SaaS·제조유통·서비스콘텐츠 세 업종의 조직 규칙 문서를 열 개 축으로 나란히 놓고, 업종이 바뀔 때 무엇이 바뀌고 무엇이 자리를 지키는지 센다. 원 자료가 같은 파일에 붙이는 200줄이 이 카테고리의 다른 글들이 쓰는 200줄과 같은 값을 다른 목적으로 재고 있다는 것도 짚는다. 뒤쪽은 프롬프트 쪽에서 아직 이 카테고리에 없던 것들 — 안티패턴 5가지와 Plan Mode를 강제 절차로 바꾸는 하드 게이트 한 줄이다.
자물쇠를 먼저 달고 출입증을 발급한다 — 빈 폴더에서 배포까지 8단계와 DB→인증 6단계
빈 폴더 하나에서 배포까지 가는 8단계와, 그중 데이터·인증 구간만 확대한 6단계를 나란히 놓는다. 두 순서를 단계별로 대조하면 여덟 중 넷만 여섯과 맞물리고 나머지는 각자 남는다. RLS를 인증보다 먼저 두는 순서의 이유, AI 기능을 붙인 뒤에 터지는 비용 폭주와 프롬프트 주입을 막는 방어선, 그리고 정책을 만든 뒤 익명 역할로 직접 공격해 보는 네 줄짜리 검증까지 이어 붙인다.
재현 없이 가설 없다 — 배포 6섹션 65항목과 디버깅 4 Phase
배포 전·중·후·롤백·보안·성능 여섯 섹션을 65개 항목으로 펼치고, 섹션마다 다른 점검 주기를 한 장의 흐름도로 그린다. 롤백 섹션은 표가 둘이라 14로 세기 쉬운데 항목은 여덟이며, 합계가 65가 되는지로 검산한다. 뒤쪽은 디버깅 — 재현·가설·검증·회귀방지 4 Phase와 13행 함정 카탈로그, 프롬프트 10패턴이다. 이 카테고리의 다른 글이 쓰는 「증상→원인→해결→예방」 4단과 이름이 같은데 카탈로그가 겹치는지 행 단위로 세어 본 결과도 함께 적는다.
차단만 하면 같은 시도가 반복된다 — Rules·Hooks·Skills 3계층과 차단 규칙 7종
에이전트를 통제하는 세 수단을 규범·강제·절차로 갈라 놓고, 비교표의 「강제력」 열이 셋 중 하나에서만 「있음」이 되는 구조를 본다. 훅 5종·차단 규칙 7종·운영 규약 6항목을 전부 펼치고, 훅 표가 요약한 사고 5가지를 차단 규칙 7종에 하나씩 배정해 어느 둘이 남는지 센다. 훅의 차단 사유가 어느 채널로 나가는지에 대해 원 자료의 표 안에서 두 행이 갈리고, 같은 카테고리의 다른 두 글도 서로 다르게 적어 두었다는 사실도 나란히 놓는다.
3계층으로 좁히고 4단으로 분해한다 — 공통 문제 10선과 현장 장애 5건
에이전트 운영 중 나는 장애를 외부 의존·자원 한도·내부 설정 3계층으로 먼저 좁히고, 증상→원인→해결→예방 4단으로 분해하는 진단 프레임. 가장 자주 나오는 문제 10선과 실제 장애 5건을 같은 틀에 넣고, 일일·주간·월간 점검 루틴과 계층별 진단 순서까지 정리한다.
권한은 프론트매터로 좁히고 통합은 Bash 한 구멍으로 — 30개 에이전트 카탈로그
7개 부서 30개 에이전트 정의서를 한 장의 표로 펼친다. 모델은 opus 10 : sonnet 20으로 갈리고 도구 변형은 세 가지뿐인데, 정작 외부 시스템 연동은 프론트매터에 드러나지 않는다. 사람 검수 필요도의 요약값과 카탈로그를 세어 본 값이 어긋나는 자리, 그리고 같은 카테고리의 다른 글에 있는 30에이전트 표와 이 표가 같은 세트가 아니라는 근거도 함께 짚는다.
규칙 문서부터 쓰면 막힌다 — 합격선 5축과 60줄 원칙
에이전트를 만든 다음이 아니라 만들기 전에 정해야 하는 것 — 무엇을 자동화 대상으로 고를지 판단하는 두 도구와, 「끝났다」를 판정하는 5축 정량 루브릭, 그리고 조직 규칙 문서를 60줄로 유지하는 이유를 정리한다. 같은 문서의 분량을 이 카테고리의 다른 글이 200줄로 부른 것과의 관계도 함께 짚는다.
에이전트 개수는 자산이 아니라 부채로 시작한다 — 개발조직에 옮길 것과 비어 있는 여섯 자리
7개 부서 30에이전트 세트에서 개발기술 4종을 자세히 보고, 나머지 26종 중 개발조직 실무로 옮길 수 있는 것과 참고만 할 것을 가른다. 재사용 후보 10종이 실제로 옮기는 것은 에이전트가 아니라 그 에이전트가 강제하던 형식이며, 도입 순서를 개수로 끊는 근거는 트리거 키워드 충돌이다. 마지막으로 이 세트에 아예 자리가 없는 여섯 영역을 짚는다.
잠재 경로는 개수의 제곱으로 는다 — 확장 구간별 운영 모델과 반복 실패 4가지
에이전트가 10개를 넘을 때 라우팅·비용·디버깅이 동시에 무너지는 메커니즘과, 5개에서 100개까지 구간별로 갈아타야 하는 운영 모델을 정리한다. 재사용 라이브러리와 권한 등급, 비용을 축별로 나누는 방법, 그리고 「그래서 효과가 얼마였나」에 답하는 증명 3종과 반복 실패 패턴 4가지까지 잇는다.
한 커맨드를 세 곳에서 부른다 — JD 5필드에서 하루가 도는 데까지
에이전트 하나를 5필드 JD로 정의하고, 여럿을 키워드 교집합이 공집합이 되게 묶고, Hook·Cron·수동 세 트리거가 같은 커맨드 하나를 호출하게 만든다. 그 위에 체크인/체크아웃 사이클과 로컬→운영 전환 시 붙여야 할 관측·통제 수단, 자리에 없을 때 지시하는 세 경로까지 잇는다.
형식은 템플릿이 복제하지만 안전장치는 복제되지 않는다 — 정의서 스키마와 30종의 품질 편차
에이전트 정의서 한 개의 구조를 프론트매터 4필드와 본문 7섹션으로 분해하고, 같은 스키마로 쓰인 30종에서 관찰된 품질 편차를 대조표로 본다. 형식 항목은 30/30으로 균질한데 권한 축소·승인 게이트·면책은 5/30, 3/30, 1/30으로 떨어진다. 그리고 경계 섹션이 실재하지 않는 이름을 지목한 건수가 원 자료의 산문과 표에서 갈린다는 점도 짚는다.
200줄은 상한이 아니라 임계다 — CLAUDE.md의 4계층 Scope와 3덩어리 7단계
세션마다 자동으로 읽히는 규칙 파일을 Enterprise→Project→User→Local 4계층으로 쌓는 규칙과, 7단계를 3덩어리로 묶어 쓰는 작성 순서를 정리한다. 같은 200줄을 이 카테고리의 다른 글이 「상한」이라 부른 것과의 관계도 함께 짚는다.
70%에서 끊는 것이 더 빠르다 — 업무 분해 3패턴과 컨텍스트 예산
복잡한 업무를 단계·파일·반복 세 가지로 나눠 시키는 법을 보고, 매 턴 전량 재전송되는 대화 이력을 어떤 임계에서 어떻게 회수할지, 세션이 끊겨도 결정이 남게 하려면 무엇을 파일로 빼야 하는지까지 정리한다.
개인은 빨라졌는데 조직 지표는 안 움직인다 — 도입 로드맵과 ROI 측정
AI 코딩 도구를 팀에 들일 때 개인 생산성은 거의 항상 오르지만 조직 전달 지표로는 잘 잡히지 않는다. 그 간극을 측정으로 메우는 방법과 6단계 도입 로드맵, 그리고 함께 보고된 반대 조건까지 정리한다.
셋으로 묶고 셋으로 가른다 — 협업 패턴 3종과 격리 3계층
파이프라인·분업·팀장-팀원 세 패턴을 실패 모드 네 개씩 붙여 나란히 세우고, 그것을 실제로 구현하는 Subagents·Agent Teams·Worktree가 상하 관계가 아니라 논리·세션·물리라는 서로 다른 격리 축이라는 점을 판단 흐름도까지 내려가 정리한다.
에이전트 한 명을 정의한다 — 필드 10개, 본문 3섹션, 검증 10항목
스킬과 에이전트를 가르는 것이 기능이 아니라 자율성이라는 데서 출발해, 정의서 한 장을 frontmatter 핵심 5·확장 5와 역할·절차·제약 3섹션으로 분해하고, 문서대로 동작하지 않는다고 보고된 항목 세 건까지 버전 표기 없음을 명기한 채로 옮긴다.
지시는 문서가 하고 차단은 설정이 한다 — `.claude/` 여덟 구성물과 프롬프트 7패턴
규칙 파일 한 장 옆에 서는 여덟 개의 구성물을 역할·적용 범위·갱신 주기로 갈라 보고, 회사 단위로 확장하는 5단계 프레임워크와 지시 한 줄을 제대로 쓰는 프롬프트 7패턴까지 잇는다.
팀을 굴리면 첫날 무엇이 멈추는가 — 운용 규칙과 완제품 환경
구조를 다 그려 놓고도 팀이 첫 턴에 멈추는 곳 — spawn 순서, 비동기 메시지, 파일 소유권, 종료 프로토콜 — 을 증상별로 짚고, 비용 3원칙과 실습 2건, 에이전트·훅·MCP를 한 벌로 묶은 오픈소스 환경 사례까지 잇는다.
누가 트리거하는가 — 확장 메커니즘을 가르는 하나의 축
MCP·커맨드·스킬·훅을 트리거 주체 하나의 축으로 가르고, 플러그인이 그 넷을 감싸는 배포 층인 이유와 조직 도입에서 안전장치가 자동화보다 앞서는 이유를 정리한다.
도구 목록이 곧 공격 표면 — 7개 내장 도구와 4대 지시 패턴
에이전트가 시스템에 영향을 주는 통로는 도구뿐이라는 사실에서 출발해 내장 도구 일곱 개를 리스크 등급으로 다시 묶고, 즉시 실행의 부작용을 제어하는 네 가지 지시 패턴 — Plan Mode·SDD·@파일 참조·이미지 입력 — 을 상황별 선택 기준까지 정리한다.
되돌릴 수 있어야 권한을 넓힌다 — CLAUDE.md 규약과 실패 모드 3분류
에이전트에게 줄 권한의 상한을 정하는 것은 신뢰가 아니라 복구 가능성이다. Git이 안전망이자 컨텍스트 공급원이 되는 구조, 검증 가능한 규약 파일이 갖춰야 할 다섯 요소, 그리고 환경 문제 20여 건이 수렴하는 세 가지 원인을 정리한다.
예외 없이 걸리는 것은 훅뿐이다 — 커맨드·스킬·훅과 플러그인 번들
사람이 부르는 커맨드, AI가 감지하는 스킬, 이벤트만 나면 실행되는 훅을 각각의 파일 구조와 차단 계약까지 내려가 보고, 다섯으로 흩어진 설정을 하나의 매니페스트로 묶는 플러그인 배포까지 잇는다.
자율성이 3세대를 가른다 — 그리고 인증 우선순위가 곧 과금 경로다
AI 코딩 도구를 자동완성·대화형·에이전틱 세 세대로 가르는 변수가 자율성 하나라는 점을 짚고, 실행·통제·지식 세 계층의 구조와 함께 인증 소스 우선순위가 어떻게 조직 비용 사고로 이어지는지를 설치 단계에서 확인한다.
deny가 항상 이긴다 — settings.json과 훅의 2차 방어선
권한을 선언형 JSON으로 통제하는 구조를 deny → allow → defaultMode 평가 순서와 5단계 설정 계층으로 정리하고, 패턴 문법으로 표현할 수 없는 조건부 규칙을 훅이 어떻게 메우는지 exit code 2 기반 차단까지 짚는다.
enforcement 없는 규칙은 위시리스트 — CLAUDE.md 3계층과 부서별 정책
규약 파일을 개인 메모에서 조직 헌법으로 올리는 3계층 구조를 배치 기준과 자동 머지 규칙까지 정리하고, 전사 정책의 실효성을 결정하는 단 하나의 키와 부서별로 정책이 갈리는 이유, 그리고 규칙 문서에서 반복되는 다섯 안티패턴을 짚는다.
MCP 도입은 기능 추가가 아니라 예산 배분이다
MCP의 N×M 문제와 3요소·전송 방식·스코프를 정리하고, 실무 6종의 인증·권한 설계와 마켓플레이스 선별 5기준을 지나 도구 하나가 점유하는 토큰을 예산으로 다루는 판단까지 잇는다.
에이전틱 코딩수정 2026-08-13
도입은 도구 선정에서 시작하지 않는다 — 순서·규약·계층 17문답
AI 에이전트를 팀에 들일 때 반복해서 돌아오는 질문 열일곱 개에 결론부터 답한다. 도입 순서와 첫 대상 선정, 규약 파일이 갖춰야 할 형태, 조직 규모별 계층, 그리고 규칙이 지켜지지 않을 때 무엇을 바꾸는가까지.
에이전틱 코딩수정 2026-08-13
붙일 수 있다와 붙여야 한다는 다르다 — 확장 메커니즘 12문답
MCP가 무엇을 해결하고 커맨드·스킬·훅이 무엇으로 갈리는지, 도구를 늘리면 무엇이 나빠지고 외부 서버를 무엇으로 거르는지를 결론부터 정리한다. 마지막 셋은 「MCP만 있으면」·「훅이면 완전히」·「스킬이면 자동으로」라는 과신을 교정하는 문항이다.
에이전틱 코딩수정 2026-08-13
에러 없이 실패하는 배포가 있다 — 운영·거버넌스 17문답
권한을 어디까지 좁히고 무엇을 첫날부터 남기는지, 장애가 나면 어떤 순서로 좁히는지를 결론부터 정리한다. 비용 폭주를 끊는 자리와 도입 성공을 판정하는 5축, 그리고 「퍼미션 모드가 몇 개인가」에 개수로 답하지 않는 이유까지 열일곱 문항.
에이전틱 코딩수정 2026-08-13
역할을 먼저 쓰고 도구를 나중에 고른다 — 에이전트 설계 10문답
에이전트 하나를 무엇으로 규정하고, 여럿을 어떤 구조로 묶고, 사람이 최종 결정하는 자리를 어디에 두는지를 결론부터 정리한다. 협업 구조 3종의 트레이드오프와 격리 3계층, 개수가 늘 때 가장 먼저 깨지는 것까지 열 문항.