모범 사례

검토 가이드 작성

검토 지침과 AGENTS.md는 새 팀원이 따를 수 있는 짧고 구체적인 규칙일 때 가장 효과적입니다. 둘 중 어디에 둘지는 규칙을 둘 위치를 참고하세요.

실제 검토에서 시작하기

무언가를 작성하기 전에 HeyDeer가 몇 개의 풀 리퀘스트를 검토하게 하세요. 반복되는 누락이나 원치 않는 댓글이 있으면 그에 대한 규칙을 한 번에 몇 개씩 추가하고, 다음 검토를 읽어 효과를 확인하세요.

짧고 구체적인 규칙 작성하기

규칙을 우선순위(Priorities), 건드리지 않을 것(Leave alone), 컨벤션(Conventions) 같은 몇 개의 제목 아래에 묶으세요.
글머리 기호 하나에 규칙 하나를 적고, 규칙이 다루는 경로, 함수, 라이브러리를 명시하세요.
이유가 분명하지 않으면 이유를 덧붙이세요.
제외 범위는 좁게 유지하세요. “스크립트에 댓글을 달지 마세요”가 아니라 “scripts/one-off/의 파일에는 댓글을 달지 마세요”처럼 적으세요. 전자는 실제 문제까지 가립니다.
코드베이스에서 가져온 잘못된 코드와 올바른 코드를 몇 줄씩 보여 주세요.
12,000자 한도보다 훨씬 짧게 유지하세요. 지침이 길어지면 컨벤션은 AGENTS.md로, 엄격한 요구 사항은 저장소 검사로 옮기세요.

포함하지 말아야 할 것

포함하지 말 것	이유	대안
들여쓰기나 import 순서 같은 포매팅 규칙	포매터나 린터가 이를 정확하게 강제합니다.	그런 도구는 CI에서 실행하세요.
“더 꼼꼼하게 검토하세요”, “아무것도 놓치지 마세요”	HeyDeer가 실행할 구체적인 내용이 없습니다.	중요한 위험을 명시하거나, 심층 깊이 또는 더 넓은 피드백 범위를 사용하세요.
“당신은 시니어 보안 엔지니어입니다” 같은 페르소나 설정	역할만으로는 무엇을 찾아야 하는지 알 수 없습니다.	그 사람이 적용할 규칙을 작성하세요.
“…이면 병합을 막으세요”, “작은 PR은 승인하세요”	지침은 검토 내용을 형성할 뿐, HeyDeer가 GitHub에서 하는 동작을 정하지 않습니다.	브랜치 규칙과 함께 “문제가 발견되면 검사를 실패로 표시”를 사용하고, 자동 승인을 사용하세요.
“테스트를 실행하세요”, “먼저 프로젝트를 빌드하세요”	HeyDeer는 코드를 읽습니다. 코드, 테스트, 빌드를 실행하지 않습니다.	HeyDeer가 읽어서 확인할 수 있는 것을 요청하세요.
“위키의 표준을 따르세요” 같은 링크	HeyDeer는 웹 링크를 열 수 없습니다.	중요한 규칙을 복사하거나, 문서를 저장소에 두거나, MCP 서버를 연결하세요.
“발견 사항을 일본어로 작성하세요”	언어는 요약과 제목에도 적용되는 설정입니다.	검토 언어를 설정하세요.

변경 전과 후

변경 전:

You are a world-class senior engineer. Be extremely thorough and
never miss a bug. Follow our standards at
https://wiki.example.com/engineering/standards. Use 2-space
indentation. Write all comments in Japanese. Run the tests before
you review, and block the PR if anything is wrong.

변경 후:

## Priorities

- Code under src/payments/ is high risk. Every call to chargeCard()
  passes an idempotency key derived from the order ID, so a retried
  request cannot charge twice.
- Retries use retry() from src/lib/retry.ts, which adds backoff.
  Replace hand-written retry loops with it.

## Leave alone

- Files under scripts/one-off/. They run once by hand and are deleted.
- Formatting. The formatter enforces it in CI.

## Conventions

- Return client errors through AppError with a stable code.

  Incorrect:

  ```ts
  return Response.json({ error: err.message }, { status: 500 });
  ```

  Correct:

  ```ts
  throw new AppError('INVOICE_NOT_FOUND', 404);
  ```

다시 작성한 지침은 페르소나와 위키 링크를 구체적인 규칙으로 바꿉니다. 나머지는 모두 위 표에 나온 위치로 옮겨집니다.