# 철학

> 결국 당신 코드를 유지보수하게 될 친구가 당신이 어디에 사는지 아는 광폭한 싸이코패스가 될 것이라고 여기고 코드를 작성하라
> — Martin Golding

merge 되는 코드가 당시의 맥락을 다 까먹을 정도로 한참 나중에도 봐야하는 코드이고, 심지어 내가 수정까지 해야하는 코드라고 생각한다.

---

# 코드 리뷰 요청 전 준비

## 커밋 컨벤션

### 기본 형식

```
[commit type]: [commit message]
```

### commit type

| 타입 | 설명 | 예시 |
|------|------|------|
| `feat` | 기능 구현 | `feat: 락커 회원 목록 검색 기능 추가` |
| `fix` | 버그 수정 | `fix: 상점 목록의 에러처리 예외케이스 대응` |
| `docs` | 문서(또는 주석) 관련 작업 | `docs: 데코레이터 옵션에 대한 문서 추가` |
| `refactor` | 리팩터링 | `refactor: createStore의 함수를 작은 함수로 분리` |
| `test` | 테스트 관련 작업 | `test: 상점 생성 테스트 추가` |
| `style` | 코드 스타일, 정렬에 관한 작업 | `style: 코드정렬 변경` |
| `design` | UI 디자인 반영에 관한 작업 | `design: 마이페이지 하단 버튼 UI 디자인 반영` |
| `build` | 빌드에 관련한 파일/설정 변경이나 추가 작업 | `build: 000라이브러리 의존성 추가` |
| `chore` | 기타 작업 | `chore: 프로덕션 빌드시 소스맵 생성하도록 변경` |

### commit message 규칙

- 작업한 내용을 간결하게 설명합니다
- 제목은 **50자**를 넘지 않아야 합니다
- 본문은 한 줄에 **80자**를 넘기지 않습니다
- 문장의 끝에 구두점(`.`)을 찍지 않습니다
- 문장은 **명사**로 끝나야 합니다
- 제목과 본문 사이는 한 줄을 개행하여 분리합니다

---

## 코드 리뷰 요청

### 코드 리뷰 요청 기준

- 리뷰 요청 전 반드시 **실행 및 기본 동작 확인** 후 요청
- 실행 전 공유가 필요한 경우 Pull Request는 **draft** 상태로 등록

### Github PR 단위

- 아사나에 이슈 카드를 만들고 최대한 **이슈 카드 하나에 연결**되는 정도로 나눈다

### Github PR 제목

- 아사나 이슈 카드 제목과 **동일**하게 구성한다
- 아사나 이슈 카드 2개 이상과 연결된다면 두 개를 아우를 수 있는 제목으로 선정한다

### Github PR 내용
PR 유형을 라벨로 표시한다.

```markdown
## 작업 배경
왜 이 작업을 하게 됐는지 간단히 설명해주세요.

## 작업 내용
무엇을 어떻게 변경했는지 설명해주세요.

## 영향 범위
변경으로 인해 영향을 받는 모듈, 컴포넌트, API 등을 적어주세요.

## 확인 방법
리뷰어가 직접 확인할 수 있는 방법을 적어주세요.
예상되는 엣지 케이스가 있다면 함께 적어주세요.

## 스크린샷 (UI 변경 시)
```

---

# 코드 리뷰 수행

## 확인 방법

- 출근 도장 찍듯이 출근하면 PR을 확인하자
- 가능한 즉시 출동
- 그 날 올라온 리뷰는 **그날 오후 5시**까지는 리뷰할 것
- PR을 확인할 때는 두 차례 확인합니다
  - **첫 번째 검토**: 코드 변경 사항을 개략적으로 파악
  - **두 번째 검토**: 세부 사항을 집중적으로 검토

## 리뷰 제출

### 🔴 Request changes

- 리뷰에 답변이 없으면 merge를 허락하지 않겠다
- 코드 수정이 없으면 merge 해선 안 된다

### 🟡 Comment

- Approve를 할 권리가 없는 사람은 없다!
- 하지만 Approve를 하기엔 찝찝하고 Request changes를 하기엔 애매할 때
- 승인절차와 관련없는 의견이나, 제안, 칭찬, 헛소리, 중얼거림

### 🟢 Approve

- 코드를 보면서 **타인에게 설명할 수 있을 정도**로 코드를 이해했다
- 해당 코드가 추가되어도 **서비스에 지장이 없다는 걸 확신**한다
- 만약 당시에 발견하지 못한 문제가 발생하더라도 **코드 작성한 사람을 함께 도울 수 있다**

코드 리뷰

> [원문](https://www.generalintelligencecompany.com/writing/agent-native-engineering) — Andrew Pignanelli (General Intelligence Company, 2026.02)  
> 핵심 내용을 우리 팀 맥락에 맞게 정리한 문서입니다.

---

## 한 줄 요약

**엔지니어 중심 조직 → 에이전트 중심 조직으로 재편하는 것.**  
AI 도구를 주는 것만으로는 Agent-Native가 아닙니다.

---

## 배경: 무엇이 바뀌었나

2024년 여름, Devin(Cognition AI)이 처음으로 비동기 코딩 에이전트를 선보였습니다.  
티켓을 던지면, 사람이 자리를 비운 사이 코드를 짜고 PR을 올립니다.

Devin 자체의 성능보다 중요한 건 **이 패턴이 만들어낸 작업 방식**입니다.

> 엔지니어가 자신의 작업을 하면서, 동시에 하위 작업을 에이전트에 위임할 수 있게 됐다.

---

## 핵심: 태스크 3등급

모든 작업을 세 등급으로 나눕니다.

| 등급 | 기준 | 처리 방식 |
|------|------|-----------|
| **Simple** | 프롬프트 한 번으로 끝남 | 에이전트 단독 처리 |
| **Manageable** | 피드백 몇 번이면 해결 | 에이전트 + 작성자 확인 |
| **Complex** | 설계와 판단이 필요 | 사람 주도 + AI 보조 |

**Simple과 Manageable은 전부 에이전트에게 위임합니다.**  
사람은 Complex에만 집중합니다.

원문의 표현:
> "Complex를 제외한 모든 태스크는 위임해야 한다. 에이전트가 조직의 실질적인 IC(Individual Contributor)가 된다."

---

## PR 2인 리뷰를 없애야 하는 이유

원문이 가장 강하게 주장하는 부분입니다.

엔지니어 한 명이 동시에 Simple 5개, Manageable 2개, Complex 1개를 병렬로 돌린다고 가정하면, 2인 리뷰 체계에서는 **자기 것 + 남의 것**을 모두 리뷰해야 합니다. 에이전트가 만들어내는 속도를 사람의 리뷰가 따라갈 수 없습니다.

> "팀원이 기능을 생각해내는 속도만큼 만들 수 없다면, 무언가가 속도를 막고 있는 것이다."

대안으로 제시하는 것:
- 코드 리뷰 봇 (Cursor Bugbot, Greptile 등)
- AI 기반 펜테스팅 서비스
- 스테이징 환경의 AI SRE

**2인 리뷰 의무를 없애되, 자동화된 품질 게이트로 대체합니다.**

---

## 코드 품질은 어떻게 지키나 (Code Slop 방지)

에이전트가 만든 코드의 품질 저하는 실제로 발생합니다. 원문의 해법:

**1. 룰셋 (CLAUDE.md / .cursorrules)**  
에이전트가 룰을 잘 따르도록 훈련되어 있습니다. 프론트엔드, 백엔드, 아키텍처, 코드 스타일 등 영역별로 룰을 정의하고 유지하는 것이 엔지니어의 새로운 핵심 업무입니다.

**2. 테스트**  
테스트는 에이전트의 보상 신호입니다. 테스트를 통과해야 머지되는 구조라면, 에이전트는 테스트가 통과할 때까지 스스로 반복합니다.

**3. 린터 / 포매터**  
eslint, python black 등. 저수준의 스타일 일관성을 자동으로 유지합니다.

---

## 조직에 미치는 변화

| 이전 | 이후 |
|------|------|
| 코드를 짜는 시간 | 무엇을 만들지 고민하는 시간 |
| 좁은 문제를 깊게 해결 | 더 많은 문제를 찾아내고 정의 |
| 긴 로드맵 | 몇 주 단위 계획, 계속 조정 |
| 엔지니어 = 구현자 | 엔지니어 = 테크리드 |

> "턴제 게임에서 실시간 전략 게임으로 바뀌는 느낌이다."

---

## 2026년 이후 전망 (원문 예측)

- IDE라는 개념 자체가 사라짐
- 사람의 코드 리뷰도 사라짐 → 사람은 제품 변화와 주요 인프라만 리뷰
- 모든 엔지니어가 PM, 모든 PM이 엔지니어화
- 팀 규모는 줄고, 1인당 산출물은 급격히 증가
- 디자인/제품 사고를 할 수 있는 사람의 가치가 상승

---

## 우리 팀에 적용한다면

```
티켓 생성 (의도와 범위를 사람이 정의)
        │
        ├─ Simple / Manageable
        │     에이전트 구현 → 작성자 셀프 리뷰 → 머지
        │
        └─ Complex
              사람 주도 + AI 보조 → 팀원 1인 리뷰 → 머지
```

당장 바꿀 수 있는 것:
1. Simple 태스크는 AI에 완전히 위임하고 셀프 리뷰로 머지
2. 2인 리뷰 의무 폐지 → Complex만 1인 리뷰
3. CLAUDE.md 또는 .cursorrules 룰셋 정비 시작

---

*원문: [Agent-Native Engineering](https://www.generalintelligencecompany.com/writing/agent-native-engineering)*

엔지니어 중심 조직 → 에이전트 중심 조직으로 재편하는 것.
AI 도구를 주는 것만으로는 Agent-Native가 아닙니다.

Agent-Native Engineering

## 개요

착수보고는 프로젝트 계약 이후, 본격적인 작업에 들어가기 전에 고객사에 전달하는 **공식 시작 알림 문서**입니다.
단순한 인사가 아니라, 앞으로의 진행 방식과 상호 역할을 명확히 정리해두는 것이 핵심입니다.

---

## 착수보고가 필요한 이유

- 고객사와 **기대치를 맞추기** 위해
- 일정, 역할, 소통 방식 등을 **사전에 합의**하기 위해
- 나중에 발생할 수 있는 **오해나 분쟁을 예방**하기 위해
- 프로젝트의 **공식적인 시작 시점을 기록**하기 위해

---

## 착수보고에 들어가는 주요 항목

| 항목 | 설명 |
|------|------|
| **프로젝트 일정 및 작업 계획** | 단계별 마감일과 작업 내용 |
| **고객사 협력사항** | 프로젝트 진행에 필요한 고객사의 준비 항목 |
| **소통 채널 안내** | 사용할 채널, 담당자, 응대 가능 시간 |
| **리스크 관리** | 예상 리스크와 대응 방안 |
| **협의 사항** | 아직 확정되지 않아 별도 논의가 필요한 항목 |

---

## 착수보고 작성 시 핵심 원칙

1. **명확하게** — 일정과 역할은 모호하지 않게 명시
2. **간결하게** — 고객사가 빠르게 읽고 확인할 수 있도록
3. **협력을 요청하는 톤으로** — 일방적 통보가 아닌 협력 요청
4. **회신을 유도하게** — 확인 요청 및 피드백 시점 명시

---

## 착수보고 vs 킥오프 미팅

| 구분 | 착수보고 | 킥오프 미팅 |
|------|----------|-------------|
| 형태 | 문서 (메일 / 메신저) | 대면 또는 화상 회의 |
| 목적 | 공식 시작 알림 + 사전 안내 | 상호 논의 및 질의응답 |
| 시점 | 계약 직후 | 착수보고 이후 |
| 필수 여부 | 권장 | 프로젝트 규모에 따라 선택 |

> 소규모 프로젝트는 착수보고로 킥오프를 대체하기도 합니다.

프로젝트를 시작할 때 고객사에 공식적으로 "이제 시작합니다"를 알리는 문서