Claude Code의 하네스(Harness)를 처음부터 전부 구축하려다 실패한 이야기

Claude Code의 운용 하네스(Harness)(rules·skills·hooks·agent 분담의 총체)는 처음부터 전부 구축하면 사용하기도 전에 유지보수로 지치게 됩니다. 실제로 빠른 단계에서 rules/ 분할이나 skill 양산에 손을 댔다가, 사용되지 않는 메커니즘만 늘어났습니다.

효과적이었던 방법은 각 단계에 「다음으로 넘어가는 신호」를 두고, 고통이 느껴질 때마다 한 단계씩 추가하는 것이었습니다.

Step	추가할 것	다음으로 넘어가는 신호
0	순수한 CLAUDE.md 1장	(처음부터 분할하지 않음)
1	목차화 (@로 별도 파일 로드)	관계없는 절을 매번 건너뛰기 시작하면
2	skill을 딱 1개만	동일한 절차 설명을 3번 반복하면
3	강력한 조작에 게이트(Gate) 설치	취소하기 어려운 조작이 절차에 등장하면
4	Codex와 역할 분담	스스로 작성하고 스스로 확인하다가, 공개 후에 누락을 발견하면
...

이하, 각 단계의 요점과 「너무 빠르면 어떤 일이 발생하는가」를 작성합니다.

처음에는 CLAUDE.md 1장에 방침과 금지 사항을 몇 줄만 적으면 작동합니다.

# 방침
사용자에게 동조하지 않고, 목적 달성을 우선한다.
# 준수 사항
...

규칙을 계속 추가하다가 관계없는 절을 매번 건너뛰게 된다면, 본체를 rules/로 나누고 CLAUDE.md를 목차로 만듭니다.

@rules/git-ops.md
@rules/test-strategy.md
@rules/security-coding.md

여기서 rules/ 분할부터 시작하면, 반복되는 고통이 나타나지 않은 단계에서 구조를 만들게 되어, 사용되지 않은 채 유지보수 대상만 늘어납니다.

동일한 절차 설명을 3번 반복하게 되면, 그 1가지 절차만 skill로 분리합니다. 전부를 skill화하지 마세요.

## 기동 조건
- 「기사를 리뷰해줘」, 「공개 전 체크해줘」라고 말했을 때
## 체크 항목
...

너무 빠르면 사용하지 않는 skill이 늘어나서, 어떤 것을 호출해야 할지 스스로 잊어버리게 됩니다. 1개를 만들어서 효과를 느낀 뒤에 다음 것을 추가하는 편이 지속 가능했습니다.

skill로 작업이 빨라지면, 이번에는 취소하기 어려운 조작(공개·삭제·push)을 멋대로 실행할 리스크가 생깁니다. 그 조작에 대해서만 명시적인 확인 게이트(Gate)를 추가합니다.

게이트 대상	통과 조건
published: true로의 변경	셀프 체크 완료·상호 리뷰 기록 있음·사용자의 공개 명시 있음

게이트를 모든 조작에 붙일 필요는 없습니다. 취소 비용이 높은 조작으로 한정합니다.

한 대의 기기로 구현과 리뷰를 모두 하면 놓치게 됩니다. 스스로 작성한 것을 스스로 확인하다가, 공개 후에 누락을 발견했다면 두 번째 기기(Codex)를 도입할 타이밍입니다.

역할	적합한 작업
Codex	구현·파일 편집·초안
Claude Code	방침 정리·리뷰·다른 관점의 확인

두 대를 운용하며 여러 세션이 되면, 「지난주에 왜 그렇게 했는지」가 사라집니다. 그래서 설계 판단은 명제문 노트에, 다음 세션으로의 인계는 handoff에 남겨두고 있습니다.

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

이것 역시 너무 빠르면 아직 아무도 다시 읽지 않는 노트의 관리만 늘어납니다. 판단이 기억나지 않아 곤란한 경험이 생긴 뒤에 추가해도 충분했습니다.

추가하는 것뿐만 아니라 버리는 것도 운용의 일부입니다. 제가 그만둔 것은 두 가지입니다. 긴 루프 작업을 대화 속에서 전부 떠안는 것(도중에 문맥이 비대해져 판단이 느슨해짐). 또 하나는 매번 어드바이저(상위 모델)에게 상담하는 것(명백한 수정 사항까지 상담하면 느려짐).

규칙을 읽어도 작업의 질이 변하지 않는다면, 그것은 솎아낼 신호입니다.

• 처음부터 전부 하지 않는다. 순수한 CLAUDE.md 1장에서 시작한다. - 각 단계에 「다음으로 넘어가는 신호」를 두고, 고통이 느껴진 뒤에 추가한다.
• 추가할 뿐만 아니라, 사용하지 않는 것을 솎아낸다.

시리즈로서, 구축된 전체 모습은 「5층 지도」, 변천의 이야기는 「rules와 skills로 나눈 이야기」에 정리해 두었습니다.

• harness17/zenn-articles — rules / skills / hooks의 실례
• Claude Code 운용 하네스의 현재 위치 (Zenn) — 구축된 도달점의 전체 모습