Claude Code용 훅, 전문 에이전트 및 자가 개선 기능을 갖춘 휴대용 엔지니어링 시스템

Claude Code에 지시를 반복하는 것에 지친 한 개발자가 ~/.claude/에 위치하며 모든 프로젝트에 자동으로 적용되는 휴대용 엔지니어링 시스템을 구축했습니다. 이 시스템은 Claude Code가 며칠 후 동일한 버그를 만나 처음부터 해결하는 반복 루프와, 한 프로젝트에서 정제된 규칙이 다른 프로젝트에는 존재하지 않는 프로젝트 간 단절이라는 두 가지 핵심 문제를 해결합니다.

시스템 구성 요소

이 시스템에는 몇 가지 주요 구성 요소가 포함됩니다:

• 헌법 (CLAUDE.md) – 가치 계층, 결정 경계, 작업 복잡도에 따른 세 가지 실행 모드를 포함한 650줄의 규칙
• 규칙을 결정론적으로 적용하는 훅 – AI가 무시할 수도 있는 제안이 아닌, 강제 푸시, 잘못된 패키지 관리자 사용, rm -rf와 같은 위험한 명령을 물리적으로 차단하는 bash 스크립트
• 세 가지 전문 에이전트 – 위임하지만 코딩하지 않는 오케스트레이터, 저장소의 격리된 복사본에서 작업하는 빌더, 그리고 문제를 수정할 수 없는(보고만 하는) 읽기 전용 검토자
• 기술 파이프라인 – 계획에서 빌드, 배송, 프로덕션까지, 대부분 자율적이지만 하나의 절대적인 게이트가 있음: 프로덕션 배포는 항상 물어봄
• 면역 시스템 – 모든 오류는 근본 원인과 실패한 접근법과 함께 기록됨. 2개 이상의 프로젝트에서 동일한 버그가 발생하면 영구적인 규칙이 되어 항체를 개발함
• 안티-굿하트 검증 – 모든 에이전트가 "완료"라고 주장하기 전에 답해야 하는 다섯 가지 질문, 왜냐하면 "모든 테스트 통과"가 앱이 작동한다는 의미는 아니기 때문

복합 엔지니어링 접근법

이 시스템은 복합 엔지니어링(Compound Engineering)에 기반합니다: 계획 → 작업 → 검토 → 복합. 그 네 번째 단계가 시스템이 스스로 개선되는 곳입니다. 개발자는 이전에 매일 반복해야 했던 구체적인 규칙들을 언급합니다: "npm이 아닌 pnpm을 사용하라," "통과하는 테스트를 삭제하지 마라," 그리고 "커밋하기 전에 테스트를 실행하라."

이 프로젝트는 https://github.com/vinicius91carvalho/.claude에서 오픈 소스이며, 모든 15개 구성 요소에 대한 전체 설명은 https://tail-f-thoughts.hashnode.dev/self-improving-engineering-system-claude-code에서 확인할 수 있습니다.