하네스 엔지니어링 03. 프로젝트 지침 파일은 어디까지 써야 할까

좋은 지침 파일은 모든 것을 담는 문서가 아니라, 무엇을 어디에 둘지 경계를 정리하는 문서다. 2편에서 하네스 엔지니어링을 “AI가 일하는 환경 전체를 설계하는 일”로 설명했다면, 이번에는 그 가까운 레이어인 프로젝트 지침 파일을 보려 한다. AGENTS.md든 CLAUDE.md든 이름보다 중요한 것은, 그 파일이 프로젝트의 entrypoint로서 어떤 역할을 맡아야 하느냐다.

프로젝트 지침 파일은 왜 필요한가

AI 코딩 도구가 프로젝트 안에서 일하려면 프로젝트 수준의 기대치와 문맥이 필요하다. 저장소 구조를 어떻게 읽어야 하는지, 무엇을 우선 지켜야 하는지, 어디서 세부 절차를 찾아야 하는지 같은 기본 정보가 없으면 agent는 매번 빈칸을 추정하게 된다. 그래서 OpenAI는 AGENTS.md를 코드베이스 탐색과 테스트, 프로젝트 관행을 위한 안내 파일로 설명하고, Anthropic은 CLAUDE.md를 프로젝트별 persistent instructions를 담는 지침 파일로 설명한다. 핵심은 파일명이 아니라, 프로젝트 규칙을 전달하는 entrypoint라는 역할이다.

왜 모든 것을 한 파일에 넣고 싶어지는가

실무에서는 한 파일에 많은 것을 모아두고 싶어진다. 역할 분리, 범위 규칙, 검증 절차, 문서 갱신 의무, handoff 규칙, 커밋 기준까지 한곳에 있으면 처음에는 체계적으로 보인다.

이런 유혹은 이해할 만하다. 프로젝트 지침 파일이 첫 진입점이라면, 중요한 것을 모두 넣어 두는 편이 덜 놓칠 것처럼 보이기 때문이다. 문제는 그 순간부터 안내문이 관제탑처럼 변하기 시작한다는 데 있다. 이 글에서는 이런 상태를 비유적으로 control plane에 가까워진 상태라고 부르겠다.

하지만 그 순간 entrypoint는 control plane에 가까워진다

예를 들어 한 파일 안에 운영 모델, 커밋 정책, 팀별 책임 구분, 문서 갱신 의무, handoff 규칙, 검증 절차, 에이전트 매핑이 모두 들어 있다고 해보자. 얼핏 보면 든든하다. 하지만 실제로는 정보 밀도가 급격히 올라가고, 어떤 항목이 기본 원칙인지 예외 처리인지 해석하기 어려워진다. 사람을 위한 설명, 절차 문서, 검증 규칙, 운영 정책이 한 파일에 함께 있으면 “모든 것이 중요해져서 아무 것도 중요하지 않게 되는” 상태가 생긴다.

이때 문제는 파일 길이 자체가 아니다. 짧은 문서도 과밀할 수 있고, 긴 문서도 역할 경계가 분명하면 비교적 안정적일 수 있다. 핵심은 정보 밀도와 역할 혼합이다. entrypoint는 agent가 방향을 잡는 곳이어야 하는데, 여기에 control plane처럼 작동하는 운영 규칙까지 몰리면 읽기 부담도 커지고, 자동 검증으로 넘겨야 할 규칙이 자연어에 묻혀 버린다.

내가 직접 설계해보며 보게 된 한계

나도 Codex 기반 프로젝트에서 AGENTS.md에 역할 분리, 범위 경계, 검증 책임, 문서 갱신 규칙, handoff 기준을 자세히 담으려 한 적이 있다. 처음에는 그렇게 해야 agent가 덜 흔들릴 것이라고 생각했다. 실제로 초반 정렬에는 도움이 됐다. 하지만 돌아보니, 그 문서는 진입점이라기보다 운영 원칙을 과도하게 집중시켜 사실상의 control plane처럼 읽히는 문서에 가까워져 있었다.

이 경험이 남긴 교훈은 단순히 “짧게 써야 한다”가 아니었다. 지침 파일을 자세히 쓰는 것과, 역할을 잘 설계하는 것은 다르다는 점이었다. 무엇을 entrypoint에 남기고 무엇을 분리된 운영 구조로 넘길지 정하는 일이 더 중요했다.

무엇을 남기고, 무엇을 분리해야 하는가

프로젝트 지침 파일에 남겨야 할 것은 비교적 명확하다.

• 저장소의 핵심 기대치
• 기본 작업 원칙
• 참조해야 할 세부 문서의 위치

반대로 아래 항목은 별도 구조로 분리하는 편이 낫다.

• 운영 절차 상세
• handoff 형식
• 평가 기준
• 문서 관리 정책
• 자동 검증 로직

예를 들어 아래처럼 나뉜 구조를 생각해볼 수 있다.

AGENTS.md 또는 CLAUDE.md: 핵심 원칙과 참조 경로
docs/ops/: 운영 절차
docs/handoffs/: handoff 형식
docs/evals/: 평가 기준

이렇게 나뉘면 프로젝트 지침 파일은 더 명확한 entrypoint가 되고, 운영 구조는 각 레이어에서 다루기 쉬워진다. 지침 파일은 안내문에 가깝고, 세부 운영은 분리된 운영 구조와 자동화 계층이 맡아야 한다.

Codex와 Claude Code에도 같은 원리가 적용된다

이 원리는 특정 도구의 팁이 아니다. Codex의 AGENTS.md와 Claude Code의 CLAUDE.md는 이름은 다르지만, 모두 프로젝트 수준의 기대치와 문맥을 전달하는 지침 파일이라는 공통점이 있다. Codex 쪽은 저장소 규칙과 기대치를 정리하는 진입점으로 이해할 수 있고, Claude Code 쪽도 공식 문서 기준으로는 프로젝트 지침 계층의 일부로 볼 수 있다.

중요한 것은 어느 쪽이 더 낫냐가 아니다. 두 도구 모두 프로젝트 지침 파일이 과밀해질 때 비슷한 문제가 생길 수 있다는 점이 더 중요하다. 파일 이름은 달라도, 과밀한 문서가 entrypoint를 사실상의 control plane처럼 바꿔 버리는 위험은 공통 운영 원리의 문제다.

마무리

프로젝트 지침 파일은 agent가 저장소에서 어떻게 행동해야 하는지 이해하는 entrypoint여야 한다. 그런데 너무 많은 운영 의미를 한 파일에 몰아넣으면, 그 문서는 안내문이 아니라 사실상의 control plane처럼 동작하게 된다. 하네스 엔지니어링 관점에서 중요한 것은 문서를 많이 쓰는 일이 아니라, 역할 경계를 분리하고 자동 검증 가능한 구조로 넘기는 일이다.

다음 글에서는 이 경계를 더 내려가 보려 한다. prose-only handoff가 왜 약한지, 그리고 handoff를 메모가 아니라 계약으로 바꾸려면 어떤 전환이 필요한지를 살펴볼 예정이다.

이 글의 한 줄 요약

프로젝트 지침 파일은 모든 운영 규칙을 몰아넣어 사실상의 control plane처럼 굴게 하는 문서가 아니라, 핵심 기대치와 참조 경로를 알려주는 entrypoint여야 한다.

다음 글 예고

다음 편에서는 prose에서 schema로 넘어가는 순간을 다뤄보려 한다. “Handoff를 남겨라” 같은 자연어 규칙이 왜 방향은 맞아도 시스템적으로는 약한지부터 살펴볼 것이다. 그리고 handoff를 메모가 아니라 계약으로 바꾸면 무엇이 달라지는지도 이어서 정리해보려 한다. 핵심은 문장을 더 엄격하게 쓰는 것이 아니라, 누락을 줄이고 검증 가능한 형식으로 바꾸는 데 있다. 이제 그 바깥 레이어를 어떻게 구조화할지 볼 차례다.