AGENTS.md

AI 코딩 에이전트를 위한 범용 작업 규칙 및 프로젝트 관리 템플릿입니다.

🚀 개요

이 저장소는 Codex, Claude, Gemini CLI, Cursor, Windsurf 같은 AI 코딩 에이전트가 프로젝트 안에서 자율적으로, 그러나 안전하고 일관되게 작업하도록 돕는 표준 가이드라인 AGENTS.md를 관리합니다.

핵심 목표는 단순합니다. 에이전트가 요청된 목표를 끝까지 수행하되, 파괴적 작업·보안 위험·범위 확장·검증 생략을 막고, 작업 결과를 문서와 Git 이력으로 추적 가능하게 남기는 것입니다.

🛠 주요 특징

• Automation First: 분석, 구현, 문서 갱신, 검증, 커밋, 푸시까지 가능한 범위에서 자동으로 완주합니다.
• Safety Rails: 파괴적 명령, 데이터 손실, 보안·비용·정책 위험은 중단 후 보고하도록 제한합니다.
• Evidence-Based Work: 파일, API, 설정, CLI 옵션을 추측하지 않고 실제 코드와 문서를 읽은 뒤 수정합니다.
• Workflow Integrity: 작업 전 상태 확인, 작은 변경, 즉시 검증, pre-commit diff 점검, 완료 보고까지 흐름을 고정합니다.
• Korean-First Communication: 사용자 보고, 커밋 메시지, 문서화는 한국어를 기본으로 작성합니다.

📁 문서 구성

• AGENTS.md: 에이전트가 실제로 따르는 공통 작업 규칙입니다.
• README.md: 저장소의 목적, 사용법, 최신 규칙 요약입니다.
• CHANGELOG.md: 사용자에게 공개 가능한 변경 요약입니다.
• HISTORY.md: 작업 배경, 검증, 결과를 남기는 내부 이력입니다.
• BACKLOG.md: §44.3에 따라 지금은 진행하지 않는 후속 개선 아이디어입니다.

📖 사용 방법

1. 이 저장소의 AGENTS.md를 프로젝트 루트 디렉터리에 복사합니다.
2. 프로젝트의 GEMINI.md, CLAUDE.md, .cursorrules 등 에이전트 진입 파일에서 AGENTS.md를 참조하게 합니다.

   @AGENTS.md
   

3. AGENTS.md의 프로젝트 설정값을 해당 프로젝트에 맞게 채웁니다. 특히 Primary Spec, History Document, Changelog, Goals Document, Backlog Document, Decision Log, Build/Test Commands를 실제 문서와 명령에 맞춰야 합니다.
4. 프로젝트 고유 정책은 가능한 한 AGENTS.md에 직접 고정하지 말고, 설정값에 지정한 명세·목표·의사결정 문서에 기록합니다.

📜 주요 규칙 요약

• 구현 원칙 (§6–§7): 기존 아키텍처와 스타일을 우선하고, 요청 범위 밖 리팩터링·전체 포맷팅·미래 대비 추상화는 하지 않습니다.
• 검증과 감사 (§14–§16): 정적 검사, 타입 체크, 테스트, 빌드, 수동 확인 중 작업에 맞는 가장 빠른 검증을 실행하고, 커밋 전에는 전체 diff를 다시 읽습니다.
• 문서화와 이력 (§17–§19): 코드·규칙 변경은 HISTORY.md, CHANGELOG.md, 관련 명세와 함께 갱신하며, 릴리즈 노트는 사용자 관점으로 분리합니다.
• 릴리스 하드닝 (§20): 기능 추가나 동작 변경을 포함한 릴리스는 버전 변경·태그·배포 전에 하드닝 후보를 정리하고, §44.3 분류에 따라 필요한 항목만 반영합니다.
• GitHub 협업 (§30–§41): Pull Request는 대규모·영향 큰 변경에 제안하고, 일반 변경은 의미 있는 단위로 커밋·푸시합니다. 공개 저장소 완성도, 독립 리뷰, 지표 무결성도 함께 다룹니다.
• GitHub AUP 경계 (§42): Actions는 저장소의 빌드·테스트·릴리즈용 CI/CD에만 사용합니다. 전사, ML, 인코딩, 스크래핑, 저장소와 무관한 cron 작업은 Actions에 올리지 않습니다.
• 모델 하네스 (§43): 실행 모델 등급과 무관하게 계획 분해, 근거 우선, 작은 변경과 즉시 검증, 상태 외부화, 자기 검증 루프, 실패 처리, 범위 준수를 동일하게 적용합니다. goal 작업은 분석 → 구현 → 감사 3단계로 수행합니다.
• 목표 완결·완성 기준 (§44): 현재 목표 완결을 우선하고, Production-Ready를 기본값으로 삼되 모든 미래 기능을 선구현하지 않습니다. 새 작업은 Blocker / Current scope / Backlog / Rejected로 분류합니다.

🔄 최근 통합된 흐름

• GitHub 협업 규칙과 AUP 준수 규칙을 추가해, GitHub를 협업·CI/CD 목적에 맞게 쓰도록 경계를 명확히 했습니다.
• 모델 하네스와 goal 실행 프로토콜을 도입해, 모델 등급이 바뀌어도 분석 → 구현 → 감사 품질 기준을 유지하도록 했습니다.
• 목표 완결과 완성 기준을 추가해, 자동 완주와 범위 통제를 함께 적용하도록 했습니다.
• 릴리스 하드닝 후보 점검을 §20에 통합해, 릴리스 직전 견고성·보안·설정 정합성·오류 처리·성능·관측성 개선점을 분류하고 선택적으로 반영하도록 했습니다.
• 특정 개인 프로젝트 저장소의 정식 명칭은 지침과 이력에서 일반 표현으로 대체했습니다.

🤝 기여하기

이 가이드라인은 계속해서 발전하고 있습니다. 더 좋은 규칙이나 개선 제안이 있다면 Issue 또는 PR을 통해 참여해 주세요.

---

Created by jeiel85