하네스의 구조 - 지침·권한·MCP·작업 분담

이 장에서 배우는 것

프로젝트 지침과 실행 권한을 분리하고 MCP 연결·작업 분담의 입력과 출력 경계를 설계한다.

지침 파일은 작업 계약을 전달한다

도서 대출 요약 프로젝트의 새 작업자가 먼저 알아야 할 것은 최신 모델 이름이 아니라 실행 방법이다. CSV의 첫 행이 제목인지, 빈 입력의 결과가 무엇인지, 어떤 검사 명령을 쓰는지 써 둔다. 지침 파일은 이런 규칙을 전달하는 문서다. 자연어로 금지했다고 해서 운영체제가 그 동작을 막는 것은 아니다. 비밀 파일을 읽지 말라는 지침과 실제 파일 접근 제한을 함께 구분한다.

2026-11-08 공식 문서에서 Codex의 AGENTS.md, Claude Code의 CLAUDE.md, Cursor의 .cursor/rules 안 .mdc, GitHub Copilot의 저장소 지침 파일을 확인했다. 파일 이름이 같아도 적용 범위와 불러오는 순서는 제품마다 다를 수 있다. 새 규칙을 쓴 다음에는 도구가 실제로 어떤 지침을 읽었는지 확인한다.

권한과 승인은 다른 질문에 답한다

Codex 문서는 샌드박스를 기술적으로 접근 가능한 범위, 승인 정책을 행동 전에 언제 확인을 요구하는지의 규칙으로 구분한다. 이 구분은 권한 설계에 유용하다. 읽기 전용 저장소 사본에서 조사하는 것과 쓰기가 가능한 작업 폴더에서 편집하는 것은 다르다. 승인 창을 닫거나 생략했다고 접근 범위가 안전해지는 것도 아니다.

실습에서는 실제 자격증명이 없는 작은 폴더만 사용한다. 파일 쓰기가 필요하면 그 폴더만 허용하고, 외부 데이터베이스나 실제 배포 도구는 연결하지 않는다. 규칙 문서에는 작업 목적과 완료 조건을 적고, 실행 환경에는 허용 경로와 도구를 설정한다. 두 층 중 하나로 다른 하나를 대신하지 않는다.

MCP와 하위 작업의 경계

MCP는 AI 응용과 외부 기능·데이터를 연결하는 프로토콜이다. 연결한 서버가 제공하는 기능, 요청 시 전달하는 데이터, 변경을 일으키는 도구를 확인해야 한다. 프로토콜을 지원한다는 이유만으로 모든 연결 대상이 신뢰할 수 있는 것은 아니다. 읽기 도구만 필요한 작업에 삭제·발송 도구까지 붙일 필요가 있는지 검토한다.

작업을 나눌 때도 같은 원리가 적용된다. 한 작업자는 CSV 파서를, 다른 작업자는 문서를 맡길 수 있다. 각자 수정 가능한 파일, 기대 출력, 검사 명령을 써야 한다. 여러 작업자의 답이 서로 동의했다고 정답이 되는 것은 아니다. 마지막에는 통합된 코드와 독립적인 기대 사례로 검증한다.

프로젝트 지침 예시

다음 AGENTS.md는 더미 저장소용 예시다. 검사 파일을 만든 다음 저장소 루트에서 실행하며, 다른 도구에서는 해당 제품이 읽는 지침 위치를 확인한다.

# 대출 요약 연습
- 실제 회원 자료·자격증명을 사용하지 않는다.
- 입력 CSV는 UTF-8이며 book_id,days 열을 사용한다.
- 빈 입력은 건수 0·평균 없음으로 표시한다.
- days는 0 이상의 정수 문자열이며 다른 값은 거부한다.
- 저장소 루트에서 python3 -m unittest discover 를 실행한다.
- 파일 덮어쓰기·네트워크 전송 기능은 이번 범위에서 제외한다.
- 변경한 파일과 실행한 검사·남은 한계를 보고한다.

직접 해 보기

더미 저장소의 AGENTS.md에 python3 -m unittest discover 명령, CSV 인코딩 UTF-8, 실제 회원 자료 사용 금지를 적는다. 도구를 쓰지 않아도 새 팀원이 이해할 수 있게 실행 위치와 빈 파일 규칙을 추가한다.

해설과 확인 기준

검사 명령만 적고 검사 파일이나 기대 동작이 없다면 지침은 아직 불완전하다. 완성 예에서는 저장소 루트에서 검사하고 빈 파일은 건수 0·평균 없음으로 보고한다고 명시한다. 실행 환경에서 비밀 파일을 볼 수 있다면 문서에 금지만 적은 것으로 접근 통제가 끝난 것은 아니다.

근거와 기준일

제품·자료 확인일: 2026-11-08. 설명 틀·대출 도구·연습·해설은 교재의 자체 구성이다. 제품별 세부 조건은 아래 공식 문서에서 해당 실행 방식과 계정 범위를 다시 확인한다.

• Codex 프로젝트 지침
• Claude Code 프로젝트 지침
• Cursor 프로젝트 규칙
• GitHub Copilot 저장소 지침
• Codex 승인과 샌드박스
• MCP 소개