학습 목표
- AGENTS.md와 프로젝트 지침 만들기의 역할과 적용 조건을 설명할 수 있다.
- README·ARCHITECTURE·docs/requirements·conventions·security·decisions 위치를 정하세요.
- 존재하지 않는 경로와 낡은 명령을 고치세요.
사전 지식
앞선 하네스 엔지니어링 설계하기를 먼저 읽으면 용어를 이해하기 쉽습니다. 이미 아는 내용이면 이 장부터 시작해도 됩니다.
개념 이해
AGENTS.md는 에이전트가 프로젝트에서 따라야 할 핵심 작업 안내를 담는 문서입니다. 파일 하나에 모든 지식을 복사하기보다 규칙과 자세한 문서의 위치를 연결합니다.
목적·스택·구조
무엇을 만드는 서비스인지, 설치된 기술과 주요 경로를 기록합니다. 프레임워크 버전별 규칙은 해당 공식 문서로 연결합니다.
코딩 규칙·확인사항·수정 금지
이름·스타일·기존 구조 보존과 작업 전 확인할 상태를 적습니다. 비밀 파일·생성 파일·다른 서비스 키 등 바꾸지 않을 경계를 명확히 합니다.
테스트 명령과 완료 조건
실제로 존재하는 명령, 필요한 에뮬레이터, 사용 가능한 연습 데이터를 적습니다. 실행하지 않은 검사를 성공으로 보고하지 않게 합니다.
관련 문서와 범위
README는 시작, ARCHITECTURE는 구조, requirements는 요구, security는 보안, decisions는 결정 이유를 담도록 나눕니다. 지침 탐색·우선순위는 도구마다 다르므로 사용 도구의 공식 동작을 확인합니다.
실제 사용 사례
프로젝트 루트에는 핵심 규칙과 docs 경로를 두고, 세부 DB 설계는 docs/architecture에 둡니다. 새로운 기능이 생겨도 모든 지침을 재작성하지 않고 담당 문서만 갱신할 수 있습니다.
단계별 실습
실습은 운영 서비스가 아닌 별도 연습 프로젝트에서 진행하세요. 기존 파일이 있다면 변경 전 기록을 남깁니다.
- README·ARCHITECTURE·docs/requirements·conventions·security·decisions 위치를 정하세요.
- 프로젝트 목적·스택·구조·금지 경로·검사 명령을 짧게 적으세요.
- 에이전트에 지침 요약과 실제 확인할 명령을 설명하게 하세요.
- 존재하지 않는 경로와 낡은 명령을 고치세요.
코드와 프롬프트
아래 코드는 직접 편집할 프로젝트 지침 초안이며 실제 경로와 명령을 넣어야 하는 환경의 예시입니다. 실제 프로젝트의 버전과 기존 구성을 확인한 뒤 필요한 부분만 적용하세요.
# 프로젝트 작업 안내
- 목적: [사용자와 핵심 기능]
- 스택: [설치 버전]
- 작업 전: 현재 변경과 관련 요구사항을 읽기
- 금지: 비밀키 출력, 무관한 서비스 설정 변경
- 검사: package.json의 실제 명령 확인
- 완료: 변경 이유, 실제 검증, 남은 위험 기록
- 문서: README.md, docs/requirements.md, docs/security.md아래 요청에서 대괄호 부분을 내 프로젝트에 맞게 바꾼 뒤 AI 도구에 전달하세요.
[프로젝트]를 읽고 AGENTS.md 초안을 작성해줘. 목적·스택·구조·코딩 규칙·작업 전 확인·수정 금지·실제 검사 명령·완료 조건·관련 문서 경로를 포함해줘. 존재하지 않는 명령은 만들지 말고 확인이 필요한 항목으로 표시해줘.자주 발생하는 문제와 해결
| 문제와 원인 | 해결 방법과 확인 기준 |
|---|---|
| 모든 설명을 AGENTS.md에 넣음 | 자세한 지식은 별도 문서로 옮기고 핵심 규칙과 경로만 유지합니다. |
| 실제와 다른 테스트 명령이 남음 | 의존성과 스크립트 변경 때 지침도 함께 갱신합니다. |
핵심 요약
- 지침은 짧고 실행 가능하게 유지합니다.
- 도구의 실제 지침 탐색 규칙을 확인합니다.
완료 확인
참고자료
확인 기준일: 2026-10-20. 요금·사용 한도·제품 기능·설정 경로는 변경될 수 있으므로 작업 직전 공식 문서와 설치 버전을 확인하세요.