• 하네스란 무엇이고 왜 필요한가
• 왜 4개 파일 구조로 나누는가
• 각 지침 파일의 역할과 작성 기준
• 실제로 부딪힌 문제와 최소 수정 보완점
• 정리
• FAQ

하네스란 무엇이고 왜 필요한가

하네스는 AI가 프로젝트 안에서 일관되게 일하도록 만드는 지침 파일 묶음입니다. 결국 하네스의 목적은 프로젝트별 규칙을 하네스 문서에 고정하는 데 있습니다. 평소에는 채팅창에 “최소 수정으로 해달라”, “운영 중인 흐름을 깨지 말라”, “검증까지 포함해달라” 같은 설명을 계속 반복하게 되는데, 하네스를 두면 그 반복을 줄일 수 있습니다. 특히 프로젝트가 Next.js App Router, TypeScript, Firebase처럼 여러 레이어를 동시에 다루는 구조라면, AI가 코드 한 줄만 고치는 것이 아니라 공개 페이지, 관리자, 고객 편집기, 데이터 구조까지 함께 건드릴 가능성이 생깁니다. 이때 기준 문서가 없으면 도구마다 답변 방식도 달라지고, 같은 요청이라도 수정 범위가 흔들릴 수 있습니다.

프롬프트 반복 대신 파일 기반 기준을 두는 이유

반복 프롬프트 예시
- 현재 구조 크게 바꾸지 말 것
- 최소 수정 우선
- package.json 기준으로 검증할 것
- 공개 페이지 / 관리자 / 고객 편집기 권한 분리 주의
- guestbooks 레거시 호환 깨지지 않게 확인할 것

이런 문장을 매번 직접 붙여 넣는 방식보다, 프로젝트 안에 하네스 기준을 문서로 남기는 방식이 더 낫습니다. 그래야 Codex, Claude, Copilot처럼 서로 다른 성향의 도구를 써도 공통 규칙이 유지됩니다. 결국 하네스의 핵심은 AI를 똑똑하게 만드는 것이 아니라, AI가 프로젝트 문맥을 먼저 읽고 움직이게 만드는 데 있습니다.

왜 4개 파일 구조로 나누는가

처음부터 모든 규칙을 하나의 파일에 몰아넣기보다, 하네스에서 공통 규칙과 도구별 보정을 분리하는 쪽이 유지보수에 유리합니다. 공통 규칙은 프로젝트 전체가 따라야 하는 기준이고, 도구별 문서는 각 AI가 가진 응답 습관을 보정하는 역할에 가깝습니다. 이 구분이 없으면 공통 문서가 너무 길어지거나, 반대로 특정 도구에만 필요한 규칙이 전체 문서를 오염시키게 됩니다.

추천하는 기본 구조

/
├── AGENTS.md
├── CLAUDE.md
├── codex.md
└── .github/
    └── copilot-instructions.md

이 하네스 구조에서 중심은 AGENTS.md입니다. 프로젝트 개요, 기술 스택, 수정 원칙, 검증 원칙, 금지 사항, 운영 주의사항처럼 누구에게나 공통으로 적용되어야 하는 내용은 여기에 둡니다. 그리고 CLAUDE.md, codex.md, copilot-instructions.md는 각 도구가 같은 프로젝트를 다룰 때 어디서 흔들리는지 보완하는 얇은 레이어로 둡니다. Codex는 작업 전에 AGENTS.md를 읽고 시작할 수 있고, 여러 위치의 AGENTS.md를 계층적으로 읽을 수 있어 더 가까운 규칙이 우선합니다. 이렇게 두면 문서 우선순위도 자연스럽게 정리됩니다. 먼저 AGENTS.md를 기준으로 삼고, 그 위에 도구별 문서가 추가 보정만 하는 형태가 가장 안정적입니다.

각 지침 파일의 역할과 작성 기준

네 개 파일이 모두 같은 중요도를 가지는 구조는 아닙니다. 역할을 분명히 나누어야 실제 작업에서 충돌이 줄어듭니다. 예를 들어 AGENTS.md는 프로젝트 헌법에 가깝고, 나머지 파일은 해석 지침에 가깝습니다. 이 차이를 명확히 적어두면 어떤 규칙이 우선하는지도 함께 정리됩니다.

파일 생성 명령어

mkdir -p .github

touch AGENTS.md CLAUDE.md codex.md .github/copilot-instructions.md

macOS, Linux, Git Bash 기준으로 기본 하네스 파일 구조를 만드는 명령어입니다.

New-Item -ItemType Directory -Path .github -Force
New-Item -ItemType File -Path AGENTS.md, CLAUDE.md, codex.md, .github/copilot-instructions.md -Force

Windows PowerShell 기준으로 사용하는 명령어입니다. VS Code 터미널을 PowerShell로 열어 바로 실행할 수 있습니다.

AGENTS.md에 들어갈 공통 기준 예시

# AGENTS.md

## 문서 목적
이 문서는 이 프로젝트에서 작업하는 AI(Codex, Claude, Copilot 포함)가 동일한 기준으로 일관되게 작업하기 위한 공통 실행 규칙이다.
모든 작업은 안정적인 수정, 기존 동작 보존, 유지보수성 향상을 우선한다.

## 문서 우선순위
- 공통 규칙은 이 문서를 최우선으로 따른다.
- 도구별 전용 문서(Claude, Codex, Copilot)는 이 문서를 보완하는 용도로만 사용한다.
- 전용 문서와 충돌하면 이 문서를 우선한다.

## 1. 프로젝트 개요
- 서비스 성격: 모바일 청첩장 + 추억(메모리) 페이지 운영 서비스
- 핵심 사용자 흐름
  - 방문자: 청첩장 공개 페이지 조회, 방명록 작성
  - 관리자: 페이지/이미지/댓글/노출기간/비밀번호 관리
  - 고객: 페이지별 비밀번호로 편집기 진입 후 내용 수정

## 9. 테스트 / 검증 원칙
- 수정 후 lint, type, build, runtime 관점에서 점검한다.
- 검증 명령은 package.json에 정의된 실제 스크립트명을 우선 사용한다.
- typecheck 스크립트가 없으면 `npx tsc --noEmit` 가능 여부를 먼저 확인한 뒤 사용한다.

## 10. 운영 주의사항
- 정적 export/배포 방식과 동적 라우트 처리 방식이 충돌하지 않는지 먼저 확인한다.
- guestbooks 관련 구조는 신규 구조 우선 + 레거시 호환 여부를 함께 점검한다.
- 공개 페이지, 관리자 페이지, 고객 편집기 흐름은 서로 다른 권한 모델로 다뤄야 한다.

AGENTS.md는 가장 먼저 읽히는 공통 기준 문서입니다. 실제 초안에서도 문서 우선순위, 프로젝트 개요, 검증 원칙, 운영 주의사항이 핵심 축으로 잡혀 있습니다. 공통 문서는 얇게 요약하는 것보다, 운영 중인 서비스에서 실수하면 안 되는 기준을 분명히 적는 쪽이 더 실무적입니다.

CLAUDE.md에 들어갈 보정 예시

# CLAUDE.md

이 파일은 AGENTS.md를 보완하는 Claude 전용 지침이다.
공통 규칙은 반드시 AGENTS.md를 따른다.
충돌 시 AGENTS.md를 우선한다.

## Claude 전용 규칙
- 설명이 길어지기 전에 먼저 결론과 수정 방향을 제시한다.
- 요청이 코드 수정이면 분석보다 수정안과 영향 범위를 먼저 제시한다.
- 불필요한 배경 설명, 추상적 설계론, 과한 리팩터링 제안은 줄인다.
- 퍼블리싱 산출물 요청일 때만 HTML/CSS/JS 분리 응답을 사용한다.
- 코드베이스 수정 요청에서는 대상 파일 형식 기준으로 바로 적용 가능한 수정안을 우선 제시한다.
- UI 피드백 요청 시 아래 순서로 정리한다.
  1. 구조
  2. UX
  3. 접근성
  4. 유지보수성
  5. 우선 수정 항목

CLAUDE.md는 공통 규칙을 다시 쓰는 문서가 아니라, Claude의 설명 습관을 보정하는 문서에 가깝습니다. 실제 초안도 결론 우선, 수정 방향 우선, UI 피드백 정리 순서처럼 응답 구조를 다듬는 항목으로 구성되어 있습니다.

codex.md에 들어갈 보정 예시

# codex.md

이 파일은 AGENTS.md를 보완하는 Codex 전용 지침이다.
공통 규칙은 반드시 AGENTS.md를 따른다.
충돌 시 AGENTS.md를 우선한다.

## Codex 전용 규칙
- 작업 전 먼저 관련 파일과 영향 범위를 파악한다.
- 요청 범위 밖 파일은 함부로 수정하지 않는다.
- 여러 파일을 수정해야 하면 먼저 수정 계획을 짧게 정리한다.
- 구조 변경이 필요한 경우 즉시 구현하지 말고 현재 구조 기준의 최소 수정안부터 검토한다.
- 퍼블리싱 산출물 요청이 아니면 HTML/CSS/JS 분리 출력보다 실제 수정 대상 파일 기준으로 응답한다.
- 검증 명령은 package.json 스크립트를 우선 사용하고, typecheck 스크립트가 없을 때만 `npx tsc --noEmit` 가능 여부를 확인한다.
- 완료 응답은 아래 형식에 가깝게 정리한다.
  - 변경 내용
  - 영향 범위
  - 확인 필요 항목
  - 남은 리스크

codex.md는 실제 수정 작업에서 흔들리기 쉬운 부분을 잡는 역할이 큽니다. 실제 초안도 영향 범위 파악, 최소 수정 우선, 검증 순서, 완료 보고 형식처럼 구현 단계에서 바로 도움이 되는 항목들로 구성되어 있습니다.

.github/copilot-instructions.md에 들어갈 보정 예시

# Copilot Instructions

Follow AGENTS.md as the primary project guide.
If there is any conflict, AGENTS.md takes precedence.

## Project context
- This project is a mobile wedding invitation and memory page service.
- It uses Next.js App Router, TypeScript, Firebase Auth, Firestore, and Firebase Storage.
- Main user flows include public invitation pages, admin pages, and client page-editor flows.

## Coding rules
- Respond in Korean for explanations and summaries.
- Prefer minimal and safe changes.
- Use HTML/CSS/JS separated output only for publishing deliverables.
- For codebase edits, answer in the target file format directly.

## Validation rules
- Prefer actual package.json scripts for lint, build, and test checks.
- If there is no typecheck script, confirm whether `npx tsc --noEmit` is valid before suggesting it.
- Mention what was verified and what still needs manual confirmation.

Copilot용 지침은 너무 길기보다 저장소 안에서 빠르게 읽히는 규칙이 더 중요합니다. 실제 초안도 프로젝트 맥락, 코딩 규칙, 검증 규칙, 완료 보고 형식을 짧고 직접적으로 정리하는 방향으로 작성되어 있습니다.

실제로 부딪힌 문제와 최소 수정 보완점

해비님이 정리한 피드백 중에서 특히 두 가지가 하네스 수정에서 가장 중요한 포인트였습니다. 첫째는 출력 형식 규칙 충돌이고, 둘째는 검증 기준 부족입니다. 이 둘은 문서가 그럴듯하게 보여도 실제 작업 단계에서 바로 문제를 만듭니다. 예를 들어 “별도 요청이 없으면 HTML, CSS, JS를 구분해 제공”이라는 규칙은 퍼블리싱 산출물 요청에는 유용하지만, 실제 Next.js TSX 파일 수정 요청에서는 오히려 작업 흐름과 충돌할 수 있습니다. 그래서 이 규칙은 전역 공통 규칙으로 두기보다, 퍼블리싱 산출물 요청일 때만 적용되도록 좁히는 편이 더 적절합니다.

출력 형식 보완 예시
- 퍼블리싱 산출물 요청일 때만 HTML / CSS / JS 분리 출력
- 코드베이스 수정 요청은 실제 수정 대상 파일 형식 기준으로 응답
- TSX 수정 요청에 HTML / CSS / JS 강제 분리는 적용하지 않음

두 번째는 검증 기준입니다. lint, type, build, runtime 확인을 적어두는 것만으로는 부족합니다. 실제 프로젝트에서는 어떤 명령을 우선 실행할지까지 문서화해야 AI가 혼동하지 않습니다. 가장 무난한 기준은 package.json 스크립트 우선입니다. 이미 팀이 쓰는 명령이 있다면 그 흐름을 먼저 따르고, typecheck 스크립트가 없을 때만 보조적으로 npx tsc –noEmit 가능 여부를 확인하는 식으로 단계화하는 편이 좋습니다. Copilot 공식 문서도 저장소 사용자 지정 지침 파일에 빌드, 테스트, 검증 방법 같은 프로젝트 맥락을 넣을 수 있다고 안내합니다. Playwright도 전체 E2E를 항상 돌리는 것보다, 변경 영향이 큰 구간만 smoke 수준으로 확인하도록 적는 편이 현실적입니다.

여기에 더해 하네스 운영 주의사항도 꼭 필요합니다. 단순한 코드 스타일 규칙보다, 실제 서비스 흐름을 지키는 규칙이 더 중요합니다. 예를 들어 정적 export와 동적 라우트가 함께 있을 때 어떤 경로가 깨질 수 있는지, 로컬 자격증명이 없을 때 fallback이 유지되는지, guestbooks 구조가 마이그레이션 과도기인지, 공개 페이지와 관리자와 고객 편집기의 권한 분리가 흐트러지지 않는지, 슬러그와 공개 여부와 노출 기간이 함께 바뀔 때 운영상 어떤 영향이 생기는지 같은 항목은 AI가 자주 놓치는 부분입니다. 이런 내용을 하네스에 넣어두면 AI는 단순히 코드를 고치는 수준을 넘어, 실제 배포 후 영향을 더 조심해서 판단하게 됩니다.

결론

이번 정리를 통해 하네스를 “AI에게 예쁘게 설명하기 위한 문서”가 아니라, “AI가 현재 프로젝트를 함부로 재구성하지 못하게 막는 실무용 기준서”로 보는 시각이 더 중요하다고 느꼈습니다. 좋은 하네스는 문서를 많이 쌓는 것이 아니라, 필요한 하네스 규칙을 정확히 배치하는 데서 시작합니다. 공통 문서는 하나로 묶고, 도구별 문서는 최소 보정만 두는 4개 파일 구조는 충분히 합리적입니다. 다만 그 구조가 실제로 힘을 가지려면 출력 형식 충돌을 막고, 검증 명령 기준을 구체화하고, 운영 주의사항을 문서에 반영해야 합니다. 결국 좋은 하네스는 규칙이 많은 문서가 아니라, AI가 어디까지 수정해도 되고 어디서 멈춰야 하는지를 분명하게 알려주는 문서입니다.

많이 받는 질문

Q. AGENTS.md 하나만 있으면 충분하지 않나요?
간단한 프로젝트라면 가능할 수 있습니다. 다만 하네스 품질을 높이려면 여러 AI 도구를 함께 쓸 경우 공통 규칙과 도구별 보정을 분리해두는 편이 유지보수에 더 유리합니다. 공통 기준은 AGENTS.md에 두고, 각 도구 문서는 응답 습관만 보정하는 구조가 가장 안정적입니다. 이런 하네스 분리는 유지보수에도 유리합니다.

Q. 도구별 문서는 얼마나 길게 써야 하나요?
길게 쓰는 것보다 하네스 역할이 분명한 쪽이 낫습니다. 공통 문서에 이미 있는 내용을 반복하기보다, Claude는 설명 순서, Codex는 수정 범위와 검증, Copilot은 짧고 직접적인 저장소 규칙처럼 꼭 필요한 하네스 보정만 적는 방식을 권장합니다.

Q. 가장 먼저 넣어야 할 핵심 규칙은 무엇인가요?
실무 기준에서는 하네스에 출력 형식 충돌 방지, package.json 기준 검증 우선, 최소 수정 원칙, 운영 주의사항, 문서 우선순위 명시를 먼저 넣는 것이 좋습니다. 이 다섯 가지가 잡혀야 AI가 멋대로 크게 리팩터링하거나, 검증 없이 수정안을 내거나, 운영 흐름을 깨뜨리는 일을 줄일 수 있습니다. 하네스의 출발점도 바로 이 기준들입니다.