컨텐츠로 건너뛰기
레시피 생태계 소스 코드 문서

AGENTS.md로 팀 동작 표준화하기

AGENTS.md는 OpenCode(및 모든 AI 에이전트)가 저장소에서 어떻게 동작해야 하는지에 대한 단일 진실의 원천입니다. 잘 작성되면 모든 기여자 — 사람이든 AI든 — 동일한 베이스라인에서 시작합니다.

이 레시피를 사용하는 경우

  • AI가 생성한 모든 PR에서 일관된 코드 스타일과 리뷰 품질을 원할 때
  • 새 팀원(사람 또는 AI) 온보딩이 너무 오래 걸릴 때
  • 팀의 여러 부분이 서로 다른 컨벤션을 가지고 있어 PR이 왔다 갔다 할 때

사전 준비

  • 저장소에 설치된 OpenCode
  • 팀의 현재 컨벤션에 대한 대략적인 아이디어 (스타일, 테스트, 에러 처리)
  • 반복할 의지 — 첫 초안은 틀릴 것입니다

단계

  1. stub에서 시작

    저장소 루트에 최소한의 구조로 AGENTS.md를 만드세요.

    # AGENTS.md

## Project overview
[한 문단: 이 프로젝트가 무엇을 하고 어떤 스택을 사용하는지]

## Build, test, lint
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Code style
[언어별 스타일 규칙]

## Testing rules
[언제 테스트를 추가할지, 무엇을 다룰지, mocking 정책]

## Commit and PR rules
[커밋 메시지 형식, PR 템플릿, 누가 무엇을 리뷰하는지]

  2. OpenCode에게 빈틈을 채워달라고 요청

    기존 코드베이스와 stub을 가리키세요. 코드에서 컨벤션을 추론할 것입니다.

    프로젝트 루트와 우리의 stub AGENTS.md를 읽으세요. 각 섹션에 대해 기존 코드의 구체적인 예시로 규칙을 채워주세요. 코드베이스가 일관되지 않는 부분에서는 우리가 따라야 할 규칙을 제안하고 일관되지 않음을 표시하세요.

  3. “하지 말 것” 섹션 추가

    명시적인 금지 항목이 가장 흔한 에이전트 실수를 방지합니다.

    ## Do not
- Do not add new top-level dependencies without discussion.
- Do not commit generated files (build/, dist/, node_modules/).
- Do not bypass the linter to make CI green.

  4. “막혔을 때” 섹션 추가

    에이전트가 정답을 모를 때 무엇을 해야 하는지 알려주세요.

    ## When stuck
- Search the codebase first (`rg`, `grep -r`).
- Read the related test file for the expected behavior.
- If still stuck, ask in #dev-help rather than guessing.

  5. 커밋하고 PR 템플릿에서 참조

    AGENTS.md를 커밋하고 .github/pull_request_template.md에서 링크하여 리뷰어가 표류를 발견할 수 있게 하세요.

  6. 배우면서 반복

    반복되는 PR 코멘트를 보면 AGENTS.md에 규칙을 추가하세요. 규칙이 마찰을 일으키면 제거하세요.

핵심 프롬프트

프로젝트 루트와 우리의 stub AGENTS.md를 읽으세요. 각 섹션에 대해 기존 코드에서 추론한 구체적인 규칙을 파일과 줄 번호 예시와 함께 채워주세요. 에이전트가 피해야 할 가장 흔한 실수들로 “하지 말 것” 섹션을 추가하세요. 이 저장소의 실제 진실의 원천(검색 명령, 테스트 파일, 채팅 채널)을 가리키는 “막혔을 때” 섹션을 추가하세요.

검증

  • 새 에이전트 세션이 시작 시 AGENTS.md를 읽고 규칙을 따름
  • 흔한 리뷰 코멘트가 줄어듦 (스타일, 누락된 테스트, 실수로 인한 커밋)
  • 파일이 짧음 (200줄 미만) — 그 이상으로 늘어나면 규칙이 너무 자세해서 유용하지 않다는 신호

흔한 실수

  • 과도한 명세: 1000줄짜리 AGENTS.md는 무시됩니다. 짧게 유지하고 자세한 문서로는 링크하세요.
  • 오래된 규칙: 컨벤션은 변합니다. 분기별 검토를 위한 캘린더 알림을 설정하세요.
  • “하지 말 것” 없음: 금지 항목 없이는 에이전트가 자체 취향을 만들어 냅니다. 명시적으로 작성하세요.

관련 문서

  • 규칙 — 모든 작업에서 OpenCode가 따르는 프로젝트 수준 지시
  • 설정 — OpenCode 동작을 제어하는 opencode.json 파일

관련 레시피

관련 문서

다음 단계