OSS 5곳의 하네스 원칙 담은 AI 템플릿, 계획·테스트·리뷰 절차 연결

마쓰모토 준타로는 2026년 10월 16일 Gibberish Lab 연구 노트에서 Zed, Sentry, OpenClaw, Bun, PostHog의 에이전트 설정을 비교했습니다. 각 프로젝트의 지침 파일과 훅, 스킬을 읽고 AI에게 판단을 맡기는 폭이 큰 순서로 다섯 사례를 배열했습니다. 이 순위는 설정을 바탕으로 내린 필자의 해석이며, 프로젝트 규모와 개발 문화도 차이에 영향을 줄 수 있다고 적었습니다. 연구 노트는 별도로 책 《プロフェッショナルAI駆動開発》 독자용 하네스 템플릿도 GitHub 저장소에서 소개합니다.

하네스는 코딩 에이전트가 저장소에서 작업할 때 따르는 지침 파일, 작업별 규칙과 스킬, 실행 훅, 권한 설정 등을 묶은 구성입니다. 각 사례의 차이는 에이전트가 문장을 읽고 판단하도록 맡기는 부분과, 훅이나 린터처럼 도구가 실행을 막거나 검사하는 부분을 어디에 두느냐에서 나타납니다.

Zed의 .rules 파일은 매 세션에 읽히므로, 구조 안내처럼 코드에서 파악할 수 있는 내용을 늘리기보다 반복해서 놓치는 구체적인 함정을 적습니다. 새 규칙은 익숙한 개발자도 놓칠 수 있고, 반복해서 발생하며, 행동으로 옮길 만큼 구체적이어야 합니다. 에이전트는 작업 중 규칙을 직접 추가하지 않고 PR 설명에 제안만 남기며, 사람이 채택 여부를 검토합니다.

Sentry는 루트의 AGENTS.md를 짧은 색인으로 두고 상세 지침과 작업 절차를 나눕니다. Sentry가 공개한 관련 스킬은 루트 파일을 60행 미만으로 작성하는 것을 목표로 하고, 100행을 넘기지 않도록 정합니다. 실제 규칙은 작업 영역별 AGENTS.md에, 절차는 스킬에 둡니다. 마쓰모토가 살핀 구성에는 29개 스킬이 있었습니다. Zed가 구조 설명을 코드 읽기에 맡기는 사례라면, Sentry는 에이전트가 어떤 자료를 읽을지 고르는 데 무게를 둡니다.

OpenClaw는 되돌릴 수 있는 일상적 판단은 에이전트가 내리도록 하면서, 새 설정 항목이나 공개 계약을 깨는 변경, 유료 서비스 이용, 파괴적 조작은 확인을 요청하게 합니다. 응답이 없다는 사실을 승인으로 처리하지 않는다는 조건도 둡니다. 새 증거 없이 같은 실패가 두 번 이어지거나 10분 동안 진전이 없으면 다른 방법으로 바꾸도록 정했습니다. 이 사례에서는 판단 범위와 멈춰야 할 조건을 주로 문장으로 규정합니다.

Bun은 반복되는 실수를 지침으로만 막지 않고 Bash 명령 실행 전 훅으로 차단합니다. 예를 들어 rustfmt를 직접 실행하면 Cargo.toml의 워크스페이스 설정을 반영하는 cargo fmt와 결과가 달라져 CI 검사와 어긋날 수 있습니다. 훅은 직접 실행을 거부하고 cargo fmt --all을 안내합니다.

PostHog의 AGENTS.md는 규칙을 자동화할 때 린터와 CI, 커밋 시 파일 검증, 스킬, 문서 지침 순으로 적용하도록 정합니다. 앞의 방식으로 처리하기 어려울 때 다음 단계로 넘어가는 구조입니다. 마쓰모토가 살핀 저장소에는 100개가 넘는 스킬이 있었고, 변경 내용에 따라 사용할 스킬도 안내했습니다. 이 사례는 기계적으로 검사할 수 있는 규칙을 에이전트가 문장을 읽고 따르는 데 맡기지 않는 방식입니다.

GitHub에 공개된 템플릿은 다섯 사례의 요소를 책의 구성을 바탕으로 묶었습니다. 사용자는 sample/의 내용을 프로젝트 루트로 옮긴 뒤 프로젝트 목적과 기술 구성, 디렉터리 역할, 주요 명령을 채웁니다. 루트 AGENTS.md는 프로젝트 개요와 작업 전 참고 자료를 안내하고, agents/README.md는 작업에 맞는 규칙과 절차를 찾는 입구가 됩니다. 아키텍처·테스트·로깅·데이터베이스 규칙은 별도 파일로 나뉘며, 스킬은 계획 작성이나 리뷰처럼 특정 작업의 절차를 담습니다. 템플릿에는 문서 목차와 제품·요구사항 서식, Claude Code 설정과 하위 에이전트 정의도 있습니다. 공통 스킬은 Codex가 참조할 수 있도록 연결해 두었습니다.

작업 프롬프트는 여덟 단계로 구성됩니다. 첫 단계에서 에이전트는 바로 구현하지 않고 필요한 질문을 한 뒤, 배경·상세 설계·테스트 영향과 새 테스트 사례·작업 순서·범위 밖 항목 등을 포함한 계획을 작성합니다. 별도 세션에서 계획을 규칙이나 요구사항에 대조하고, 테스트 사례도 요구사항의 수용 조건과 비교합니다. 구현은 검토된 계획을 따르며, 계획에 없는 변경이 필요하면 진행을 멈추고 보고하도록 합니다.

구현 뒤에는 변경 관련 기존 테스트를 실행해 결과를 기록하고 새 테스트를 작성합니다. 각 새 테스트는 먼저 실패하는지 확인한 다음 구현을 수정해 통과시키는 순서입니다. 계획의 기대 결과를 바꿔야만 테스트가 통과하는 경우에는 테스트를 고치는 대신 멈추고 보고하게 합니다. 이어 설계 일치 여부, 경계 사례, 보안을 각각 맡은 하위 에이전트가 병렬로 리뷰합니다. 사람에게는 변경의 데이터 흐름과 설계 판단, 위험이 큰 부분을 설명하고, 최종 판단은 사람의 리뷰에 둡니다. 여덟 번째 단계의 테스트 주도 리팩터링은 매 기능 구현 직후가 아니라 정기적으로 수행하는 절차입니다. 시작 전 테스트가 통과하는지 확인하고, 한 번에 한 변경씩 진행하며 테스트가 실패하면 그 변경을 되돌립니다.

템플릿에는 본番 데이터베이스 쓰기를 막는 Claude Code 훅도 포함됩니다. 저장소 README는 장애 조사 등으로 본番 DB 읽기 접속이 필요한 경우의 안전망으로 설명하며, 연결 정보는 개발자 저장소에 두지 않는 방식을 기본으로 제시합니다. 훅은 PROD_DATABASE_URL 참조나 PROD_DB_HOSTS에 적힌 호스트 이름으로 본番 접속을 판별해 읽기를 허용하고, 쓰기·스키마 변경·마이그레이션·시드 입력과 파일에서 전달하는 SQL 실행을 차단합니다. 명령 문자열을 검사하는 방식이라 우회 가능성이 남고, 실행에는 Node.js가 필요합니다. README는 읽기 전용 DB 계정과 데이터베이스 자체의 쓰기 권한 제한도 설명합니다. AGENTS.md의 지침은 도구 권한을 강제하지 않으므로, 실제 권한과 외부 연결은 도입하는 프로젝트 설정에 따라 달라집니다.

이 저장소는 완성된 앱이나 테스트 코드·기반을 제공하는 배포물이 아니라, 프로젝트에 맞게 채워 쓰는 템플릿입니다. 일부 규칙과 명령은 책의 청구서 SaaS 사례를 바탕으로 하며, README는 프로젝트 정보와 명령, 대상 경로, 도구 설정을 도입 환경에 맞추는 구조를 안내합니다. 필요하지 않은 DB 규칙이나 Sentry 스킬은 빼거나 사용 중인 구성에 맞게 바꿀 수 있습니다. 저장소 README에 따르면 배포 라이선스는 아직 정해지지 않았습니다.