TL;DR

  • 프로젝트의 성격과 작업 방식에 맞는 AGENTS.md 파일을 만들고 저장소별 지침을 추가하는 안내임.
  • 프로젝트 맥락은 레거시 유지보수·현대화, 그린필드 프로토타입·장기 제품, 모노레포, 오픈소스, 내부 도구, 규제 환경 중에서 선택함.
  • 추가 지침이 필요한 초점 영역으로 백엔드, UI, 인프라, 데이터, 머신러닝, 테스트, 보안, 문서화 등을 선택함.
  • 프로젝트에서 사용하는 기술 스택과 코드 작성·개발 선호 사항을 지정함.
  • 파일을 저장소 루트에 저장하고, 실제 명령과 적용 가능한 규칙만 남긴 뒤 커밋하고 변경 사항에 맞춰 갱신함.

프로젝트 맥락

  • 프로젝트에 가장 잘 맞는 유형 하나를 선택함.
  • 레거시 — 유지보수만: 버그를 수정하고 계속 실행되도록 유지함. 리팩터링은 하지 않고, 안전한 최소 변경만 수행함.
  • 레거시 — 적극적 현대화: 단계적으로 개선하고 재구성함. 테스트를 전제로 리팩터링을 허용함.
  • 그린필드 — 프로토타입·MVP: 새 프로젝트에서 속도를 우선함. 단순하게 유지하고 일부 기술 부채를 수용함.
  • 그린필드 — 장기 제품: 처음부터 구조, 테스트, 문서를 갖춘 지속 가능한 새 제품을 구축함.
  • 모노레포 — 여러 프로젝트 혼합: 하나의 저장소에 여러 앱과 패키지가 있으므로 경계와 각 영역의 관례를 준수함.
  • 오픈소스 라이브러리·패키지: 공개 API 안정성, 시맨틱 버전 관리(semver), 변경 기록, 하위 호환성을 고려함.
  • 오픈소스 프로젝트: Kubernetes나 이 사이트와 같은 공개 앱·플랫폼·웹사이트를 대상으로 하며, 기여자 작업 흐름, 호환성, 명확한 문서를 고려함.
  • 내부 도구·스크립트: 팀을 위한 실용적이고 읽기 쉬우며 절차가 간결한 도구를 대상으로 함.
  • 규제 환경: 금융·의료 등에서 감사 추적, 데이터 보호, 엄격한 검토를 고려함.

초점 영역

  • 추가 지침이 필요한 영역을 선택함.
  • API 및 백엔드, UI 및 접근성, 모바일 앱, 인프라 및 배포, 데이터 파이프라인, 머신러닝 및 AI, 테스트, 보안, 디자인 시스템 및 UX, 문서화.
  • 저장소 관례, 주요 경로, 도메인 제약, 특정 작업 지침을 사용자 지정 지침으로 추가할 수 있으며, 마크다운을 지원하고 공유 링크에 포함됨.

기술 스택

  • 프로젝트에서 사용하는 기술을 하나 이상 선택함.
  • 언어: Bash / Shell, C, C#, C++, Dart, Elixir, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Scala, Swift, TypeScript.
  • 프런트엔드: Angular, Astro, HTMX, Next.js, Nuxt, React, React Router / Remix, Solid, Storybook, Svelte, SvelteKit, Tailwind CSS, Vite, Vue.
  • 백엔드: ASP.NET Core, Bun, Deno, Django, Express, FastAPI, Fastify, Flask, Gin, GraphQL, gRPC, Laravel, NestJS, Node.js, OpenAPI / REST, Phoenix, Ruby on Rails, Spring Boot, Symfony.
  • 모바일: Android (Jetpack Compose), Expo, Flutter, iOS (SwiftUI), Kotlin Multiplatform, React Native.
  • 데이터베이스: Cassandra, ClickHouse, Drizzle ORM, DynamoDB, Elasticsearch, MongoDB, MySQL, PostgreSQL, Prisma, Redis, SQLAlchemy, SQLite.
  • 인프라·클라우드: Ansible, AWS, Azure, Cloudflare, Docker, Firebase, GitHub Actions, GitLab CI, Google Cloud, Helm, Kafka, Kubernetes, Nginx, OpenTelemetry, Prometheus / Grafana, Pulumi, RabbitMQ, Supabase, Terraform, Vercel.
  • 테스트: Cypress, Jest, JUnit, k6, Playwright, pytest, Testing Library, Vitest.
  • 데이터·머신러닝: Airflow, dbt, Hugging Face Transformers, Jupyter, LLM APIs, MLflow, pandas, Polars, PyTorch, scikit-learn, Spark.
  • 디자인: 디자인 토큰, Figma.

작업 선호 사항

  • 선택 사항인 작성·개발 선호 사항을 지정함.
  • 간결한 기술 영어: ASD-STE100 간결 기술 영어로 작성함.
  • 코드 주석 최소화: 명백하지 않은 의도만 설명하고 코드를 반복해서 설명하지 않음.
  • 테스트 주도 개발(TDD): 테스트를 먼저 작성하고 레드-그린-리팩터 사이클을 따름.

파일 사용 방법

  • AGENTS.md를 저장소 루트에 저장함.
  • 각 <placeholder>를 프로젝트에 맞는 실제 명령으로 바꿈.
  • 모든 규칙을 읽고 프로젝트에 맞지 않는 규칙은 제거함.
  • 파일을 짧게 유지하고, 영역별 지침이 적용되는 경우를 명시함.
  • 파일을 커밋하고 기술 스택이나 작업 절차가 바뀌면 갱신함.

AGENTS.md 소개

  • AGENTS.md는 코딩 에이전트에 지침을 제공하는 공개 형식임.
  • 많은 코딩 에이전트가 저장소 루트의 파일을 읽음.
  • 자세한 내용은 agents.md에서 확인할 수 있음.