Claude Code 운영 하네스(Harness)를 '작게 나누어 수정할 수 있는 형태'로 만든 3가지 이유

Claude Code / Codex의 운영 하네스(Harness)(rules·skills·hooks·agent 분담의 총체)를 수개월간 운영하며 남은 설계 원칙은 3가지입니다.

원칙	한 줄 요약	지키지 않았을 때 발생한 일
편집 반경을 작게 유지하기	1파일 1토픽	테스트 방침의 1줄 수정으로 옆의 보안 섹션이 무너짐
...

이하, 각 원칙의 근거를 작성합니다.

처음에는 CLAUDE.md

한 페이지에 모든 규칙을 작성했습니다. Git 조작, 테스트 방침, 보안 관점이 1개 파일에 혼재된 상태입니다.

테스트 방침의 문구를 수정했을 때, 옆의 보안 섹션에서 인덴트(Indent)가 무너져 에이전트(Agent)가 보안 규칙을 읽지 않고 건너뛰었습니다. 1줄의 수정이 관계없는 규칙에 파급되었습니다.

rules/

로 분할하고 CLAUDE.md를 목차로 만들었더니, 편집 반경이 1개 파일 안에 수렴했습니다. git diff를 통해 변경 사항이 1개 파일에 닫혀 있음을 확인할 수 있었고, 인접 규칙으로의 파급이 사라졌습니다.

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

너무 많이 나누면 '어느 파일에 무엇이 있는지' 찾는 비용이 증가합니다. 글로벌 18개, 프로젝트 고유 8개 정도가 상한선이었습니다.

다음에 발생한 문제는 모든 것을 규칙(rules)에 작성해 버리는 것이었습니다.

기사 공개 전 체크를 규칙에 작성해 두었더니, 코드 구현 세션에서도 매번 읽어 들여졌습니다. 스킬(skill)로 옮겼더니 태스크(Task)에 따라 기동하게 되었고, 저장 시의 문체 체크는 훅(hook)으로 설정했더니 호출을 잊어버리는 일도 없어졌습니다.

종류	트리거 조건	사용처
rules	상시 적용	매 태스크마다 지켜야 할 제약 (Git 조작, 보안)
...

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

트리거 조건이 다른 것을 한곳에 섞으면, 상시 실행되어야 할 것이 호출 누락으로 빠지거나, 필요할 때만 있으면 되는 것이 매번 노이즈가 됩니다.

하네스의 부품은 추가하는 것뿐만 아니라 제거하는 경우도 있습니다. 사용하지 않는 규칙을 남겨두면 에이전트가 읽어 들이는 양이 늘어나 판단이 둔해집니다.

중요한 것은 하나의 규칙을 제거해도 다른 규칙이 망가지지 않는 것입니다. 실제로 릴리스 전 체크 스킬이 "sprint-contract.md의 완성 조건 리스트를 참조하여 검증한다"라고 적혀 있었던 시기가 있었습니다. sprint-contract.md의 작성 방식을 바꾸자 릴리스 전 체크도 망가졌습니다.

규칙 간의 참조는 "관련으로서 존재를 알고 있다" 정도에 그치고, 실행 순서에 대한 의존성은 만들지 않도록 했습니다. 규칙을 읽어도 작업의 질이 변하지 않는다면, 그것은 솎아낼 신호입니다.

편집 반경을 작게 유지하기: 1개 파일의 수정이 다른 곳에 파급되지 않는 구조
트리거 조건으로 계층 나누기: rules/skills/hooks/advisor를 섞지 않기
버려질 수 있는 단위로 보유하기: 규칙 간의 순서 의존성을 만들지 않기

시리즈로서, 구축된 전체 모습은 5층 지도, 처음부터 구축하는 방법은 빌드 순서로 정리해 두었습니다.

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