# AGENTS.md: 의도를 적어야 리뷰가 수렴한다

이 저장소를 수정하는 모든 코딩 에이전트(Cursor, Claude Code, Codex 등)를 위한 지침이다.
특정 도구나 언어에 종속되지 않는다.

**한 줄 원칙: 머릿속에 있는 맥락을 코드 옆으로 옮겨라.**

"이 분기는 우리 환경에서 실행되지 않는다."
"이 함수는 null이 들어와도 안전하다."
"이건 일부러 뺐다."

이런 판단이 머릿속이나 PR 설명에만 있으면 리뷰는 매번 다시 묻는다.
AI 리뷰는 모든 PR마다 똑같이 묻는 끈질긴 주니어다.
해법은 논쟁이 아니라 주석이다.

AI 리뷰는 티켓 번호가 붙은 근거 주석을 읽고, 근거가 타당하면 같은 지적을 반복하지 않는다.
아래 습관은 지적을 한 번에 영구히 닫기 위한 것이다.

---

## 규칙

### 1. 반박은 PR 설명이 아니라 코드 주석에 쓴다

PR 설명은 휘발성이다.
다음 리뷰는 그것을 읽지 못하고, 같은 지적이 되살아난다.
이유는 코드 옆에 티켓 번호와 함께 남긴다.

```
/* 반복자 안전성 (검토 완료, #1234): delete()는 노드의 링크만 교체하고
 * 삭제된 노드만 해제한다. 미리 확보한 커서는 항상 살아남는다. */
```

주의할 점이 있다.
리뷰는 주석의 존재가 아니라 근거의 타당성을 검증한다.
코드와 맞지 않는 근거는 주석이 있어도 다시 지적된다.
**주석은 음소거 버튼이 아니다.**

티켓 번호는 실재하는 티켓이어야 한다.
지어낸 번호는 반박이 아니라 형식일 뿐이다.

### 2. 맨몸 TODO를 남기지 않는다

하지 않기로 결정했다면 이유를 쓴다.
진짜로 미룬 것이라면 티켓 번호를 붙인다.

```
나쁨:  /* TODO: 로깅과 알람 추가 */

좋음:  /* 텔레메트리 의도적 생략 (#1234): 삭제는 이미
        * 변경 알림 이벤트로 관측된다. */

좋음:  /* TODO(#4001): 알람 인프라가 들어오면 속도 제한 알람 추가 */
```

### 3. 동시성 주석은 "왜"와 "누가 경합하는지"를 쓴다

리뷰어가 추측하지 않고 잠금(lock)을 검증할 수 있어야 한다.

```
/* 수신 경로는 데몬·타이머·알림 처리기가 쓰기 잠금으로 변경하는
 * 자료구조를 순회한다. 순회는 읽기 잠금으로 잡고,
 * 판정은 복사본에서 수행한다. */
```

### 4. 불변조건은 주석이 아니라 기계에 맡긴다

주석은 사람에게 알린다.
단언(assertion)은 미래의 위반자를 멈춘다.

| 가정의 종류 | 맡길 곳 |
|---|---|
| 구조체 배치·크기 | 컴파일 타임 단언 |
| 잠금 규율 | 공용 접근자의 런타임 단언 |
| 데이터 불변조건 | 테스트 |

### 5. 함수의 계약은 정의부에 한 줄로 쓴다

null 허용 여부, 반환 규약, 소유권 이전 여부를 정의된 자리에 밝힌다.
그래야 호출부와 호출부의 리뷰가 추측하거나 되묻지 않는다.

```
/* null 허용: 입력이 null이면 null을 반환한다.
 * 정리(teardown) 이후에 호출해도 안전하다. */
```

### 6. 경계의 의미를 이름에 담는다

`end`는 배타적(exclusive)으로 읽힌다.
마지막 원소를 포함한다면 `last`로 부른다.

이름은 계약이다.
이름과 실제가 어긋나는 지점에서 off-by-one 오류가 산다.
이름을 바꿀 수 없다면 호출부에 규약을 주석으로 남긴다.

### 7. 빌드·설정 조건은 함수 머리에 쓴다

리뷰도 사람도 설정 파일까지 읽지 않는다.
특정 플래그에서만 빌드되거나 현재 대상에서 실행되지 않는 코드라면 맨 위에 밝힌다.

```
/* FEATURE_X가 켜진 경우에만 빌드된다.
 * 현재 대상에서는 꺼져 있다(여기서는 죽은 코드). */
```

### 8. 인스턴스가 아니라 클래스를 고친다

리뷰가 어떤 패턴의 사례 하나를 찾으면, 같은 파일과 모듈에서 형제 사례를 검색해 같은 커밋에서 함께 고친다.
그러지 않으면 다음 리뷰가 다음 형제를 찾고, 이 과정이 끝없이 반복된다.

안전 래퍼를 새로 추가했다면 모든 호출부의 계약을 같은 커밋에서 점검한다.

### 9. 근거 주석은 주장이다. 계속 참으로 유지한다

근거 주석은 작성 시점에만 참이고, 설명 대상 코드가 바뀌면 썩는다.
그런 주석이 의존하는 동작(잠금 방식, null 처리, 자원 해제 시점)을 수정했다면 같은 커밋에서 주석을 재검증한다.

낡은 안전 주장은 없느니만 못하다.
코드가 막 움직인 바로 그 자리에서 리뷰를 침묵시키기 때문이다.

---

## 푸시 전 점검

- [ ] 내가 기각한 지적마다 이유를 티켓 번호와 함께 코드 주석으로 남겼는가?
- [ ] 맨몸 TODO가 남아 있지 않은가? ("의도적 생략 + 이유" 또는 `TODO(#1234)`)
- [ ] 새로 추가하거나 변경한 잠금에 누가 경합하는지 적었는가?
- [ ] 배치·잠금·데이터 가정을 단언이나 테스트로 옮겼는가?
- [ ] 패턴의 사례 하나를 고쳤다면 형제 사례를 검색해 함께 쓸었는가?
- [ ] 근거·계약 주석이 설명하는 코드를 건드렸다면 그 주석이 아직 참인가?
- [ ] 리뷰가 끝난 뒤에 병합했는가?