에이전틱 워크플로우 설계란 — 내 설정이 4개월 만에 3계층이 된 이유

에이전틱 워크플로우가 뭔가

AI 에게 매번 지시를 다시 쓰는 대신, 판단 기준과 절차를 미리 파일로 적어두고 그 위에서
일을 시키는 것이다. 대화가 끝나도 파일은 남으므로, 다음 대화는 같은 기준에서 시작한다.

“프롬프트를 잘 쓴다”와는 다르다. 프롬프트는 이번 한 번이고, 워크플로우는 다음번에도 같은
결과가 나오게 만드는 구조다. 매번 “커밋 메시지는 한글로 써줘”라고 말하는 것과, 그 규칙을
파일에 적어 모든 대화에 자동으로 실리게 하는 것의 차이다.

내 설정은 4개월간 커밋 287개를 거치며 3계층이 됐다.¹ 처음부터 이렇게 설계한 게 아니라
한 층으로 다 하려다 실패해서 나뉜 것이다. 이 글은 그 과정이다.

한 파일에 다 넣으려다 터졌다

처음엔 CLAUDE.md 하나였다. 모든 대화에 자동으로 실리는 규칙 파일이다. 규칙이 생길 때마다
여기에 붙였다.

크기가 이렇게 움직였다.

시점	크기
2026-04-24 (최초)	1,771B
2026-07-30 (정점)	13,837B
2026-07-31 (하루 뒤)	9,304B
2026-08-27 (현재)	11,823B

7월 30일에 정점을 찍고 다음 날 4,533B 를 덜어냈다. 32.8% 가 하루 만에 빠졌다.

커밋 네 개가 하루에 몰려 있다. 절반은 옮긴 것이고 절반은 지운 것이다.

커밋	무엇을	줄어든 양
`f8bb01b`	환경변수 관리 → 개인 머신 프로파일로 이동	814B
`20e10c2`	JPA ddl-auto 보완 규칙 제거	1,267B
`b22e9bf`	브라우저 도구 순서 → `chrome-mcp` 스킬로 분리	2,007B
`afd3753`	Brainstorming 규칙 제거 (Artifact 로 대체)	445B

옮긴 것이 2,821B, 아예 지운 것이 1,712B 다. 기준은 하나였다.
모든 대화에 실릴 값어치가 있는가. 없으면 조건부로 읽히는 자리로 내리고, 그럴 자리도
없으면 지운다.

브라우저를 조종할 때만 필요한 규칙이 파이썬 버그를 고치는 대화에도 실리고 있었다. 그 비용은
매 대화마다 나가는데, 실제로 쓰이는 건 가끔이다. 그래서 “그 작업을 할 때만 읽히는” 스킬로
내렸다.

여기서 첫 번째 층이 갈렸다. 항상 참인 것은 CLAUDE.md, 조건부로 참인 것은 스킬.

규칙은 지켜지지 않으면 규칙이 아니다

두 번째 갈래는 성격이 다르다. 규칙을 적어놨는데 안 지켜지는 문제였다.

처음에 이렇게 썼었다.

항상 쉽게 풀어서 설명한다. 전문용어를 그대로 던지지 않고,
처음 보는 사람도 이해할 수 있게 쓴다.

잘 안 지켜졌다. 커밋에 이유를 적어뒀다.²

“쉽게 풀어서” 는 지켰는지 스스로 확인할 방법이 없어 실제로는 잘 지켜지지 않았다.
셀 수 있는 기준으로 바꾼다.

“쉽게”는 판정할 수 없다. 쓴 쪽도 읽는 쪽도 지켰는지 알 수 없으니, 안 지켜져도 아무 일이
안 일어난다. 그래서 셀 수 있는 것으로 바꿨다.

전	후
항상 쉽게 풀어서 설명한다	결론 3줄이 먼저다
(없음)	근거 표는 5행 이내
무엇→왜→그래서 순서로 말한다	(삭제 — 결론 우선과 순서가 반대라 충돌)

마지막 줄이 중요하다. 규칙을 더하다 보면 서로 모순되는 두 규칙이 생긴다. “결론을 먼저”와
“무엇→왜→그래서 순서로”는 같이 지킬 수 없다. 하나를 지우는 것도 설계다.

같은 정리를 한 번 더 했다. “요청된 것만 한다”는 취지가 세 곳에 흩어져 있었는데, 한 곳으로
모으면서 부정형을 검증 가능한 완료 기준으로 바꿨다.³

- 요청된 것만 하고 더 하지 않는다
+ 변경된 모든 줄이 사용자 요청으로 직접 추적 가능해야 한다

“더 하지 않는다”는 어디까지가 더인지 알 수 없다. “모든 줄이 요청으로 추적 가능한가”는
diff 를 보고 한 줄씩 판정할 수 있다. 판정할 수 있어야 어긴 걸 알 수 있고, 어긴 걸 알아야
규칙이 작동한다.

부탁과 차단은 다르다

세 번째 갈래가 가장 늦게 왔다. 규칙을 아무리 판정 가능하게 써도, 그건 여전히 부탁이라는
것이다.

맥 4대의 설정을 자동 동기화하는데, git pull 이 충돌하면 사람이 올 때까지 그 머신은 멈춘다.
그래서 Claude Code 를 무인으로 불러 충돌을 풀게 했다. 문제는 권한이다. git 을 다뤄야 하니
셸을 줘야 하는데, 주면 임의 명령이 가능하다.

프롬프트에 금지 목록을 적었다. 강제 푸시 금지, reset --hard 금지, 시크릿 파일 금지.

그리고 도구 범위도 좁혔다. --allowedTools "Bash(git status:*)" 처럼.

강제되지 않았다. 허용 목록 밖 명령이 그대로 실행됐다. 즉 프롬프트의 금지 목록도, 도구
범위 지정도 모델에 대한 요청이지 기술적 차단이 아니었다. 대체로 지켜지지만 보장은 없다.
무인 실행에서는 그 차이가 결정적이다.

훅으로 옮기니 막혔다. 훅은 도구를 부르기 직전에 도는 스크립트라 모델의 협조가 필요 없다
— 코드가 판정하고 코드가 막는다.

이 이야기는 훅은 언제 막고 언제 못 막나 에
따로 썼다. 여기서 중요한 건 결론이다. 세 번째 층은 “모델이 지켜주기를 기대하지 않는 층”
이다.

같은 구분이 무인 실행 밖에서도 성립한다. 정적 사이트의 도식 규칙을 CSS·스크립트·문서
세 곳에 나눠 뒀더니 문서에만 적어둔 항목에서만 위반이 나왔다 —
도식 3개가 18×18px 로 찌그러졌다 에 실측을 적었다.

남의 플러그인도 층으로 나눈다

내가 쓴 파일만 층이 있는 게 아니다. 설치한 플러그인 세 개도 역할이 겹쳐서, 어느 상황에
무엇을 쓸지 라우팅 규칙을 따로 적어야 했다.⁴

층	도구	맡는 것
프로세스	superpowers	코드 쓰기 전에 멈추고 계획하게 하는 절차
오케스트레이션	OMC	큰 작업을 에이전트 여럿에 나눠 실행
지식	ECC rules	언어별 컨벤션 (java·ts·react·python)

셋이 겹치는 지점이 실제로 있었다. 예를 들어 “완료 검증”을 superpowers 도 하고 OMC 도 한다.
둘 다 돌면 같은 검증이 두 번 나간다. 그래서 완료 검증은 superpowers 것 한 번만, OMC
verifier 는 OMC 모드 안에서만 으로 정했다.

ECC 는 아예 플러그인으로 설치하지 않고 규칙 파일만 뽑아 왔다. 훅과 에이전트 67개가
앞의 둘과 충돌하기 때문이다. 그중에서도 rules/common 은 일부러 뺐는데, 이유가 두 개다.

CLAUDE.md 에 이미 있는 원칙과 중복·충돌한다
paths 스코프가 없어 모든 세션에 상시 로드된다 — 10개 파일 전부 frontmatter 가 없는
것을 확인했다 (grep -l 'paths:' → 0)

앞의 두 층에서 배운 기준이 여기에도 그대로 적용됐다. 항상 실리는 것은 값어치를 증명해야
한다.

정리하면

4개월간 층이 세 개로 갈렸고, 갈린 기준은 매번 달랐다.

층	갈린 기준	실패했던 방식
CLAUDE.md ↔ 스킬	모든 대화에 실릴 값어치가 있는가	한 파일에 다 넣어 13.8KB 까지 불림
판정 가능한 규칙	지켰는지 셀 수 있는가	“쉽게 설명한다” 같은 판정 불가 문장
훅	모델 협조 없이 강제되는가	프롬프트 금지 목록을 차단으로 착각

공통점이 하나 있다. 세 번 다 먼저 실패했고, 실패의 모양을 보고 나서 층을 갈랐다. 처음부터
“3계층으로 설계하자”고 시작한 게 아니다.

그래서 이 글은 “이렇게 설계하세요”가 아니다. 설정이 안 지켜지거나, 너무 무거워지거나,
지켜졌는지 알 수 없을 때 그게 층이 갈릴 신호라는 이야기다.

다음 글에서는 이 위에서 실제로 돌리는 워크플로우 하나를 처음부터 끝까지 뜯어본다.

~/dotfiles 레포. 2026-04-24 최초 커밋, 2026-09-07 기준 287 커밋. claude/CLAUDE.md 는 33회, claude/settings.json 은 48회 수정됐다. ↩
커밋 b54bfe9 (2026-08-05) “설명 방식 규칙을 판정 가능한 기준으로 교체”. ↩
커밋 26a2b65 (2026-08-22) “요청 범위 규칙 중복 3곳을 1곳으로 통합”. ↩
claude/CLAUDE.md “플러그인 조합 라우팅” 섹션, 커밋 286a10d (2026-07-07). ECC 제외 근거는 claude/plugins-manifest.md. ↩