Claude Code 운영 하네스를 5개 계층으로 정리하기 (rules/skills/agent 지도)

Claude Code / Codex를 몇 달간 사용하다 보면 rules, skills, hooks가 늘어나면서 "목록은 있지만 지도는 없는" 상태가 됩니다. 늘어난 부품들은 다음의 5개 계층으로 다시 정렬하면 정리할 수 있었습니다.

이 기사는 각 계층이 무엇인지, 그리고 어떻게 연계되는지를 정리한 것입니다. 대상은 Claude Code나 Codex를 사용하기 시작하여 rules, skills, hooks가 늘어났지만 전체상을 파악하지 못하고 있는 개인 개발자입니다. "하네스(Harness)"는 에이전트의 운영을 뒷받침하는 지시, 설정, 분담의 총체를 가리킵니다.

실례로서, 이 기사를 관리하고 있는 리포지토리 harness17/zenn-articles의 구성을 사용합니다. 또한, 하네스에는 커리어 및 개인용 규칙도 섞여 있지만, 여기서는 범용적인 개발 운영 계층만을 다룹니다.

도입 직후에는 하나의 CLAUDE.md에 전부 작성했습니다. 곧 힘들어졌고, 지금은 본체를 rules/로 나누고 CLAUDE.md를 목차로 만들었습니다.

# 글로벌 규칙
사용자에게 동조하지 않고, 목적 달성을 우선한다.
@rules/advisor-strategy.md
...

입구는 2단계 구조입니다. 글로벌 CLAUDE.md가 모든 프로젝트 공통의 18개를 읽어들이고, 프로젝트 측의 CLAUDE.md가 고유한 규칙을 추가로 읽어들입니다. 목차로 만들어 두면 "테스트 방침만 수정하기"를 할 때 거대한 파일 하나를 건드리지 않아도 됩니다.

규칙(rules)은 호출하지 않아도 상시 적용되는 제약입니다. 수가 늘어나면 하나씩은 파악할 수 없으므로 기능 그룹으로 관리합니다.

그룹	주요 규칙	역할
개발 규율	git-ops / sprint-contract / karpathy-coding-principles / comand-check	구현 전의 합의와 다루는 범위의 제어
...

예를 들어 구현 전에 완성 조건을 선언하게 하는 sprint-contract는 다음과 같은 제약입니다.

【스프린트 컨트랙트】
구현 내용: 〇〇 기능 추가
완성 조건:
...

규칙이 "묵묵히 적용되는" 것에 반해, 스킬(skills)은 "호출했을 때만 실행되는" 정형 작업입니다. 반복되는 절차를 스킬로 옮겨 의뢰하는 말을 짧게 만들었습니다.

여기서 중요한 것은 계층마다 발화 조건이 다르다는 점입니다.

종류	발화 조건	예
rules	상시 적용 (묵묵히 적용됨)	git-ops, security-coding
...

훅(hooks)은 "자동으로 실행되는 계층"입니다. 이 리포지토리에서는 기사를 저장했을 때 문체의 NG 어구를 경고하는 훅을 넣어두었습니다.

{
"hooks": {
"PostToolUse": [
...

직접 손을 움직이는 계층입니다. 전부 하나의 모델로 처리하지 않고 역할별로 나누고 있습니다.

에이전트	위치 설정	적합한 작업
Codex	구현 담당	파일 편집 · 테스트 · 기사 초안
...

어드바이저(advisor)를 호출하는 것은 별도의 관점이 효과적인 국면으로 한정했습니다. 통상적인 편집까지 상담하면 느려지기 때문입니다. 기사에 대해서는, 작성한 에이전트 스스로가 공개 판단을 완결짓지 않도록 상호 리뷰(작성자 ≠ 리뷰어)를 게이트로 설정하고 있습니다.

그 자리의 채팅에서 "A가 아니라 B로 했다"라고 결정해도, 몇 주 후에는 이유가 희미해집니다. 나중에 기사로 쓰기 위해서라도 설계 판단은 대화 외부에 남겨두지 않으면 약해집니다. 그래서 설계 판단은 명제문을 제목으로 한 노트로 남기고 있습니다.

---
description: "판단의 요지를 한 문장으로"
alternatives: "검토한 대안"
...

이것은 설계 판단을 기록하기 위한 범용적인 메커니즘이며, 노트의 내용(구체적인 안건명 등)은 드러내지 않습니다. 다음 세션으로의 인계는 handoff, 저장 시의 자동 체크는 hooks로 나누어져 있습니다.

정적인 지도를 하나의 태스크로 세로로 관통하면, 5개 계층은 하나의 흐름이 됩니다. 예를 들어 "브라우저 확장 기능에 소규모 기능을 추가하여 공개한다"라면 다음과 같이 진행됩니다.

처음에 sprint로 완성 조건을 선언하고, Codex가 구현하며, 망설여지면 advisor에게 상담하고, security-review와 pre-release로 확인한 뒤, 공개하고, 마지막으로 판단과 인계를 기록 계층에 남깁니다. 각 계층을 위에서 아래로 한 번 통과하게 됩니다.

• 하네스(Harness)는 「입구 → 제약 → 정형 작업 → 실행 → 기록」의 5개 계층으로 조망할 수 있습니다.
• rules (묵묵히 적용됨) / skills (호출함) / hooks (자동) / advisor (난관)에 따라 발화 조건이 다릅니다.
• 늘어난 부품은 종류별로 정리하며, 신규 프로젝트에서는 계층 단위로 취사선택합니다.

「제로에서 어떻게 구성할 것인가」, 「왜 이러한 형태로 만드는가」는 별도의 기사로 나눌 예정입니다. 운영을 바꿔온 변천 과정 그 자체는, Zenn 버전의 원문 기사인 Claude Code 운영 하네스의 현재 위치 — rules/skills/agent를 5개 계층의 지도로 만들었다 와, 그 이전의 Claude Code 운영을 수개월에 걸쳐 재검토하여 rules와 skills로 나눈 이야기에 정리되어 있습니다.

• harness17/zenn-articles — 이 기사를 관리하고 있는 리포지토리 (rules / skills의 실례)
• Zenn 버전의 원문 기사 — 동일한 내용을 다소 자세하게 작성한 것