AGENTS.md

작성할 내용

새로 합류한 팀원에게 필요한 컨벤션을 적으세요. 코드 구성 방식, 이름 규칙, 사용할 헬퍼와 라이브러리, 오류와 테스트를 다루는 방식 등이 해당합니다.

• “읽기 쉬운 코드를 작성한다”처럼 경험 있는 엔지니어라면 누구나 아는 내용은 빼세요. HeyDeer와 코딩 에이전트는 이미 일반적인 관행을 따릅니다.
• 몇 개의 제목 아래에 항목 하나당 컨벤션 하나씩 적으세요.
• 각 컨벤션이 다루는 경로, 함수, 라이브러리를 명시하세요.
• 이유가 분명하지 않다면 함께 적으세요. 그러면 HeyDeer가 컨벤션에 명시되지 않은 경우도 판단할 수 있습니다.
• HeyDeer가 건드리지 않아야 할 부분처럼 검토에만 해당하는 안내는 REVIEW.md나 검토 지침에 두세요. HeyDeer가 해당하는 모든 풀 리퀘스트에서 반드시 확인해야 하는 요구 사항은 저장소 검사에 두세요.

AGENTS.md

# Conventions

## Structure

- API handlers live in src/api/, one file per resource.
- Background jobs live in src/jobs/ and are idempotent, because
  the queue can run a job twice.

## Helpers

- Retries use retry() from src/lib/retry.ts, which adds backoff.
- Read the current time through now() from src/lib/clock.ts, so
  tests can set it.

## Errors and tests

- Return client errors through AppError with a stable code, such
  as new AppError('INVOICE_NOT_FOUND', 404).
- Each new API handler has a test in tests/api/ that runs against
  a real database.

루트 파일과 하위 디렉터리 파일

저장소 루트에 AGENTS.md를 추가하세요. 자체 컨벤션이 필요한 디렉터리에는 src/payments/AGENTS.md처럼 별도 파일을 둘 수 있습니다.

HeyDeer가 읽는 각 파일에는 저장소 루트부터 해당 파일의 디렉터리까지 있는 AGENTS.md 파일이 적용됩니다. 더 깊은 위치의 파일은 상위 파일에 내용을 더하며, 서로 충돌하면 더 깊은 위치의 파일이 우선합니다.

src/payments/AGENTS.md

# Payments

- Every call to chargeCard() passes an idempotency key derived
  from the order ID, so a retried request can't charge twice.
- Amounts are integers in cents. Never use floating point for money.

HeyDeer는 이 파일들을 풀 리퀘스트에서 읽으므로, 이 파일을 수정하는 풀 리퀘스트는 수정된 버전으로 검토됩니다. 풀 리퀘스트가 바꿀 수 있는 것을 참고하세요.

CLAUDE.md 사용하기

AGENTS.md가 없는 디렉터리에서는 HeyDeer가 대신 CLAUDE.md를 읽습니다. 두 파일이 모두 있는 디렉터리에서는 AGENTS.md만 읽습니다.

제한

• HeyDeer는 루트부터 적용되는 가장 깊은 파일까지 이 파일들을 최대 32KiB까지 읽습니다. 한도를 넘는 파일은 잘리고, 그보다 깊은 위치의 파일은 제외됩니다.
• HeyDeer는 CLAUDE.md의 @docs/testing.md 같은 가져오기를 따라가지 않습니다. 컨벤션은 파일 안에 직접 작성하세요.