## 한눈에 보기
 
- **무엇인가**: AI 모델 자체를 제외한 모든 제어 구조(컨텍스트 파일, MCP, 훅, CI 게이트 등)를 설계하는 엔지니어링 분야
- **왜 필요한가**: 프롬프트는 '부탁'에 불과하기 때문에, 반복되는 실수를 막기 위해서는 '구조적 강제'가 필요함
- **누가 제안했는가**: 미첼 하시모토(Mitchell Hashimoto), 2026년 2월
- **검증 사례**: OpenAI 엔지니어 3명이 5개월간 서비스 코드 수정 없이 하네스 개선만으로 성능 향상 입증
---
 
## 1. 문제 인식: 왜 AI 비서는 같은 실수를 반복하는가
 
최신 AI 코딩 에이전트를 업무에 도입한 사용자라면 한 번쯤 깊은 좌절을 경험합니다. "분명히 그렇게 하지 말라고 했는데"라며 프롬프트를 수정해도, AI는 얼마 지나지 않아 동일한 실수를 반복하거나 작업 중간에 길을 잃습니다.
 
이것은 단순히 모델 지능의 문제가 아닙니다. 미첼 하시모토는 AI 코딩 에이전트의 반복적 실패를 해결하기 위해 **'하네스 엔지니어링(Harness Engineering)'** 개념을 제시했습니다. AI에게 '부탁'하는 수준을 넘어, 실수가 반복될 수 없는 **시스템적 구조**를 만드는 것이 핵심입니다.
 
---
 
## 2. 하네스란 무엇인가
 
초원을 자유롭게 달리는 야생마는 힘이 대단하지만, 경마장에 그대로 풀어놓으면 본능적으로 울타리를 넘거나 관중석으로 돌진합니다. 이때 필요한 것이 바로 마구(Harness)입니다. 고삐로 방향을 잡고, 안장으로 인간의 의도를 전달하며, 끈으로 트랙 안에서만 달리게 유도합니다.
 
하네스는 모델의 지능을 억누르는 장치가 아닙니다. 오히려 모델의 강력한 에너지를 올바른 방향으로 집중시켜 더 빠르고 정확하게 목표에 도달하게 하는 구조적 제약(Structural Constraint)입니다.
 
> **"모델이 아닌 모든 것이 하네스다."**
 
Claude의 `claude.md` 파일, MCP(Model Context Protocol), 스킬, 훅(Hook) 등 AI 모델 자체를 제외하고 모델을 제어하기 위해 설계된 모든 아키텍처적 요소가 하네스에 해당합니다.
 
---
 
## 3. 프롬프트 엔지니어링과의 차이
 
| 구분 | 프롬프트 엔지니어링 | 하네스 엔지니어링 |
|------|--------------------|--------------------|
| 본질 | 부탁(Request) | 강제(Enforcement) |
| 동작 방식 | AI의 판단에 의존 | 결정적 강제(Deterministic) |
| 실패 시 | AI가 망각·이탈 가능 | 시스템이 다음 단계 차단 |
| 비유 | "안전모를 꼭 써주세요" | 안전모 미착용 시 출입문 자체가 열리지 않음 |
 
프롬프트는 본질적으로 "이렇게 해주세요"라는 부탁입니다. 강제성이 없기 때문에 AI는 언제든 망각하거나 어길 수 있습니다.
 
반면 하네스 엔지니어링은 "이 규칙을 지키지 않으면 다음 단계로 넘어갈 수 없다"는 시스템을 구축합니다. 실수를 AI의 지능이나 판단에 맡기는 것이 아니라, **실수가 불가능한 환경을 설계**하여 성능을 보장합니다.
 
---
 
## 4. 컨텍스트 부패와 기억의 닻
 
AI 작업이 길어질수록 성능이 급격히 떨어지는 현상을 컨텍스트 부패(Context Decay)라고 합니다. AI의 컨텍스트 창(Context Window)에는 한계가 있어, 대화가 길어지면 앞부분의 중요한 지침을 잊어버리게 됩니다.
 
하네스 엔지니어링은 이를 해결하기 위해 `claude.md`나 `agent.md` 같은 컨텍스트 파일을 활용합니다. 이는 휘발되는 채팅 이력과 대비되는 **기억의 닻(Anchor)** 역할을 합니다.
 
- **매 세션의 온보딩**: AI는 매번 새로 출근하는 신입 사원과 같습니다. 세션이 리셋되거나 대화가 길어져 앞 내용을 잊더라도, 하네스 시스템은 AI가 작업을 시작할 때마다 이 파일을 다시 읽도록 강제합니다.
- **지속성 확보**: 프로젝트의 핵심 규칙을 파일로 고정함으로써, 에피소드 중심의 기억이 아닌 **시스템 중심의 지속적 맥락**을 유지하게 합니다.
---
 
## 5. 사례: OpenAI의 검증
 
OpenAI의 엔지니어 3명은 **5개월 동안 실제 서비스 코드는 단 한 줄도 수정하지 않은 채**, 오직 시스템 구조 개선만으로 비약적인 성능 향상을 증명했습니다. 그들이 주목한 명제는 다음과 같습니다.
 
> **"지능(Intelligence)이 아니라 하네스(Harness)가 병목이다."**
 
### OpenAI가 구축한 하네스의 4대 요소
 
1. **`agent.md` 제작** — AI가 반드시 준수해야 할 명시적 업무 지침서 확립
2. **CI 게이트(CI Gate) 구축** — 코드를 저장할 때마다 사람이 아닌 시스템이 자동으로 테스트를 수행하여 무결성 검증
3. **도구 경계 설정** — 에이전트가 접근할 수 있는 권한과 작업 범위를 기계적으로 제한
4. **피드백 루프** — AI가 스스로 결과를 리뷰하고 규칙을 보강하는 자기 교정 구조 설계
### 추가 사례: LangChain
 
LangChain의 사례에 따르면, 모델은 그대로 둔 채 하네스만 개선했을 때 에이전트 성능 순위가 **30위권에서 5위권으로 급상승**했습니다. 이는 AI 성능을 좌우하는 핵심 레버가 모델의 체급이 아닌 **하네스의 정교함**에 있음을 시사합니다.
 
---
 
## 6. 하네스를 지탱하는 3가지 기둥
 
### 6.1. 컨텍스트 파일: 60라인의 법칙
 
1,000페이지짜리 매뉴얼은 AI를 압도하여 오히려 성능을 저하시킵니다. OpenAI는 보편적인 지침을 담은 파일을 **60라인 이하**로 유지할 것을 권장합니다.
 
**점진적 강화(Incremental Hardening)**
 
미첼 하시모토는 처음부터 완벽한 가이드를 쓰지 않습니다. 에이전트가 실패할 때마다 그 원인을 분석하여 '딱 한 줄의 규칙'을 추가합니다. 이를 통해 하네스는 살아있는 교훈의 아카이브가 됩니다.
 
### 6.2. 자동 강제 시스템: 성공은 조용히, 실패는 시끄럽게
 
린터(Linter)와 훅(Hook)을 통해 AI의 결과물을 기계적으로 검사해야 합니다.
 
성공한 테스트 로그 4,000줄을 AI에게 모두 보여주는 것은 컨텍스트 윈도우를 낭비하고 AI를 산만하게 만듭니다.
 
> **"Success is quiet, failure is loud."**
> 성공은 침묵하고, 실패만 소란스럽게 보고하여 AI가 오직 수정이 필요한 부분에만 지능을 집중하도록 해야 합니다.
 
불필요한 성공 로그는 AI의 시야를 가리는 노이즈가 됩니다.
 
### 6.3. 가비지 컬렉션(Garbage Collection)
 
나쁜 코드 패턴이나 낡은 문서가 쌓이면 AI는 이를 학습하여 실수를 복제합니다. 주기적으로 가비지 컬렉션 에이전트를 가동해 불필요한 코드를 청소하고, 실제 코드와 문서 간의 괴리를 바로잡아 시스템의 청결도를 유지해야 합니다.
 
---
 
## 7. 엔지니어 역할의 진화: 코더에서 감독으로
 
이제 엔지니어의 역할은 직접 코드를 한 줄씩 짜는 '선수'에서, AI가 최상의 성과를 낼 수 있는 환경을 설계하는 '감독'으로 변모하고 있습니다. 리처드 파울러(Richard Fowler)는 이를 '엄밀함의 재배치(Relocation of Rigor)'라고 정의했습니다.
 
- **과거의 엄밀함**: 코드의 구문(Syntax)을 정확히 맞추는 것
- **현재의 엄밀함**: 에이전트가 올바르게 동작할 수밖에 없는 **시스템적 제약(Constraints)** 설계
---
 
## 8. 자가 진단 질문
 
AI 에이전트가 기대만큼 성능을 내지 못한다면, 더 비싼 모델로 바꾸기 전에 스스로에게 질문해 보아야 합니다.
 
> **"나는 AI에게 성능을 내달라고 '부탁'하고 있는가, 아니면 성능이 나올 수밖에 없는 '하네스'를 설계했는가?"**
 
---
 
## 핵심 용어 정리
 
| 용어 | 의미 |
|------|------|
| **하네스(Harness)** | 모델 자체를 제외한 모든 제어 구조 |
| **컨텍스트 부패(Context Decay)** | 작업 길이에 비례해 AI 성능이 저하되는 현상 |
| **결정적 강제(Deterministic Enforcement)** | 시스템 구조를 통해 규칙 준수를 강제하는 방식 |
| **점진적 강화(Incremental Hardening)** | 실패 사례를 분석해 한 줄씩 규칙을 누적하는 방법론 |
| **엄밀함의 재배치(Relocation of Rigor)** | 코드 구문에서 시스템 제약 설계로 엔지니어링 초점이 이동하는 현상 |
 
---
 
## 참고 인물 및 출처
 
- **미첼 하시모토(Mitchell Hashimoto)**: 'Harness Engineering' 개념 제안 (2026년 2월)
- **OpenAI 엔지니어링 팀**: 하네스 개선만으로 성능 향상 검증
- **리처드 파울러(Richard Fowler)**: '엄밀함의 재배치' 개념 제시
- **LangChain**: 모델 변경 없이 하네스 개선만으로 에이전트 성능 순위 상승 사례

AI 에이전트의 성능 병목은 모델의 지능이 아니라, 모델을 둘러싼 구조(Harness)에 있다.

하네스 엔지니어링(Harness Engineering)

## 개요

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

---

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

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

---

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

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

---

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

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

---

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

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

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

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

착수보고란 무엇인가

# DB 스키마 변경 워크플로우

> **목적** 마이그레이션 충돌 방지 및 프로덕션 반영 사고 예방
> **대상** 온보더즈 개발팀 전원
> **도구** Drizzle ORM + Drizzle Kit

---

## 1. 핵심 원칙

1. **마이그레이션 파일은 손으로 수정하지 않는다** — 자동 생성된 파일만 커밋
2. **동시에 스키마를 건드리는 작업은 한 명만** — 착수 전 팀에 공유

---

## 2. 환경별 DB 구성

| 환경 | 용도 | 데이터 | 반영 방법 |
|---|---|---|---|
| **local** | 개인 개발 | 개인 더미 | `drizzle-kit push` (자유롭게) |
| **development** | 통합 테스트 | 소량 더미 | 배포 Pre-deploy Step으로 자동 실행 |
| **staging** | 프로덕션 검증 | 소량 더미 | 배포 Pre-deploy Step으로 자동 실행 |
| **production** | 서비스 운영 | 실데이터 | 배포 Pre-deploy Step으로 자동 실행 |

> ⚠️ `drizzle-kit push`는 local 전용. 
> development/staging/production에서는 절대 사용 금지.

---

## 3. 스키마 변경 플로우

```
스키마 변경 착수 전
  └─ 슬랙에 "DB 스키마 작업 시작합니다" 공유
       └─ 다른 팀원 동시 작업 여부 확인

브랜치 생성 → 스키마 수정 → 마이그레이션 생성
  └─ drizzle-kit generate

PR 생성
  └─ PR 본문에 변경된 테이블/컬럼 명시 (아래 템플릿 참고)
  └─ 팀원 리뷰 필수 (최소 1명 approve)

develop 머지 → development DB 자동 반영 확인

staging 머지 → staging DB 자동 반영
  └─ 마스킹된 프로덕션 데이터로 주요 기능 검증
  └─ 이상 없으면 프로덕션 배포 진행

프로덕션 배포
  └─ Railway Pre-deploy Step에서 migrate 자동 실행
  └─ migrate 성공 시 코드 배포 진행 / 실패 시 배포 중단
```

---

## 4. 마이그레이션 생성 규칙

```bash
# 스키마 파일 수정 후
npx drizzle-kit generate

# 생성된 파일 반드시 확인
# 예상한 변경만 들어있는지 diff 검토 후 커밋
git add drizzle/migrations/
git commit -m "db: add users.phone column"
```

**커밋 컨벤션**

```
db: <변경 내용 한 줄 요약>

예시)
db: add users.phone column
db: rename orders.status → orders.state
db: drop deprecated sessions table
```

---

## 5. 마이그레이션 충돌 해결

팀원 간 마이그레이션이 겹치면 타임스탬프 순서가 꼬일 수 있음.

### 충돌 시 절차

1. **작업 중단 — 직접 수정하지 않는다**
2. 슬랙에 상황 공유
3. 두 브랜치 중 **나중에 생성된 쪽**이 리베이스
4. 리베이스 후 마이그레이션 재생성

```bash
# 나중 브랜치에서
git rebase dev

# 스키마 충돌 해결 후 기존 마이그레이션 파일 삭제 후 재생성
npx drizzle-kit generate
```

> 마이그레이션 파일을 손으로 합치지 말 것. 반드시 재생성.

---

## 6. 프로덕션 반영 절차

> Railway 기준. staging 검증 → 프로덕션 Pre-deploy migrate → 코드 배포 순서.

### Step 1 — development 확인

PR 머지 후 development DB에 자동 반영된 결과를 최소 하루 확인.

### Step 2 — staging 검증

stating 머지 시 staging에 자동 마이그레이션 실행.

- staging DB는 프로덕션과 동일한 스키마 + 개발환경 데이터로 구성
- 변경된 테이블/컬럼과 관련된 주요 기능 직접 테스트
- 슬랙에 staging 검증 완료 공유 후 프로덕션 배포 진행

### Step 3 — 프로덕션 배포 (migrate 자동 실행)

Railway  설정으로 배포 전 migrate 자동 실행.

```
# Railway 대시보드 → Service → Settings → Deploy → Pre-deploy Command
npx drizzle-kit migrate
```

- migrate 성공 → 코드 배포 자동 진행
- migrate 실패 → 배포 자동 중단 (코드는 변경되지 않음)

### Step 4 — 배포 후 smoke test

- 변경된 기능 직접 확인
- 이상 없으면 슬랙에 완료 공유

### 프로덕션 반영 금지 시간대

| 금지 시간대 | 사유 |
|---|---|
| 월~금 16:00–18:00 | 퇴근 시간 |
| 금요일 17:00 이후 | 주말 대응 불가 |
| 클라이언트 데모 당일 | 리스크 회피 |

### staging DB 데이터 관리

프로덕션 데이터를 staging에 주기적으로 동기화. 개인정보는 반드시 마스킹 후 복사.

```sql
-- 마스킹 예시 (users 테이블)
UPDATE users SET
  email = CONCAT('user_', id, '@example.com'),
  phone = '010-0000-0000',
  name  = CONCAT('테스트유저', id);
```

> 동기화 주기는 팀 상황에 맞게 결정. 최소 월 1회 권장.

---

## 7. PR 스키마 변경 체크리스트

PR에 스키마 변경이 포함된 경우 아래 항목을 PR 본문에 포함.

```markdown
## DB 변경 사항
- [ ] 변경된 테이블: `테이블명`
- [ ] 변경 종류: 컬럼 추가 / 수정 / 삭제 / 인덱스 / 제약조건
- [ ] 데이터 마이그레이션 필요 여부: Y / N
- [ ] development 반영 확인: Y / N
```

---

## 8. 자주 하는 실수 & 금지 행동

| 행동 | 이유 |
|---|---|
| `drizzle-kit push`를 개발/운영에서 사용 | 마이그레이션 히스토리가 남지 않음 |
| 마이그레이션 파일 직접 수정 | 체크섬 불일치로 이후 마이그레이션 실패 |
| 스키마 변경을 팀에 알리지 않고 착수 | 충돌 원인 |
| 금요일 오후 프로덕션 반영 | 주말 장애 대응 불가 |

---

*최초 작성: 2026.03 | 다음 리뷰: 분기별*

마이그레이션 충돌 방지 및 프로덕션 반영 사고 예방

DB 스키마 변경 워크플로우

# AI Skills 운영 가이드

## 1. AI Skill이란 무엇인가

AI Skill은 **반복적으로 수행되는 작업을 AI가 안정적으로 실행할 수 있도록 정의한 작업 모듈**이다.
단순한 프롬프트 저장이 아니라 **작업 절차, 실행 규칙, 검증 기준을 함께 정의한 자동화 프로토콜**이다.

Skill을 사용하면 AI가 동일한 작업을 수행할 때 다음이 보장된다.

* 작업 절차의 일관성
* 실행 규칙 준수
* 결과 검증 가능

즉, Skill은 **AI 사용을 개인 프롬프트 수준에서 팀 표준 작업 프로세스로 전환하는 방법**이다.

---

# 2. Skill의 구성 요소

Skill은 다음 세 가지 요소로 구성된다.

### 1) 작업 절차 (Workflow)

AI가 수행해야 하는 단계적 작업 순서이다.

예시

* PR 리뷰 목록 수집
* 리뷰 단위 코드 수정
* 리뷰별 커밋 생성
* 커밋 push
* 리뷰 reply 작성
* 다음 리뷰 처리

---

### 2) 실행 규칙

작업 수행 시 반드시 따라야 하는 규칙이다.

예시

* 리뷰 단위로 작업 처리
* 각 리뷰마다 별도 커밋 생성
* 커밋 push 이후 reply 작성
* 특정 CLI 명령 필수 사용

---

### 3) 승인 요건 (검증 기준)

AI가 작업을 올바르게 수행했는지 확인하기 위한 기준이다.

예시

* 모든 리뷰 코멘트에 답글 작성
* 각 리뷰마다 별도 커밋 생성
* 모든 커밋이 push 완료
* 린트 / 빌드 테스트 통과

검증 기준이 없는 Skill은 재사용 안정성이 낮다.

---

# 3. Skill이 필요한 이유

AI를 프롬프트 방식으로 사용할 경우 다음 문제가 발생한다.

* 같은 프롬프트 반복 입력
* 작업 순서 불일치
* 검증 기준 누락

Skill을 사용하면 다음 효과가 있다.

* 반복 작업 자동화
* 작업 절차 표준화
* 결과 검증 가능

즉, Skill은 **AI를 대화 도구에서 작업 자동화 도구로 전환하는 구조**이다.

---

# 4. 우리 팀 Skill 운영 원칙

## 1) Skill은 Repository에 포함한다

Skill은 개인 환경이 아니라 **프로젝트 저장소에 포함하여 팀 전체가 공유한다.**

예시 구조

```
.agents/skills/      (Codex용)
.claude/skills/      (Claude용)
```

Repository에 포함하면 팀원이 동일한 Skill을 사용할 수 있다.

---

## 2) 공통 Skill + 도구별 어댑터 구조 사용

하나의 Skill을 여러 AI 도구에서 사용할 수 있도록 **공통 규칙과 도구별 설정을 분리한다.**

권장 구조

```
/ai-skills
    /core
        pr-review-flow.md
    /codex
        SKILL.md
    /claude
        SKILL.md
```

구성 설명

* **core**
  작업 절차와 규칙의 원본 정의

* **codex / claude**
  각 AI 도구에서 실행하기 위한 설정 파일

이 구조를 사용하면 **동일 Skill을 여러 AI 환경에서 사용할 수 있다.**

---

## 3) Skill에는 승인 요건을 반드시 포함한다

Skill에는 반드시 **자동 검증 가능한 기준**을 포함해야 한다.

예시

* 리뷰별 개별 커밋 생성
* 모든 커밋 push 완료
* 리뷰 reply 작성 완료
* 린트 / 빌드 테스트 통과

검증 기준은 **AI 작업의 정확도를 보장하는 핵심 요소**이다.

---

# 5. Skill 사용 방식

개발자는 간단한 요청으로 Skill을 실행할 수 있다.

예시

```
PR 리뷰 반영해줘
```

AI는 해당 요청을 Skill과 매핑하여 다음 절차를 수행한다.

1. PR 리뷰 수집
2. 리뷰 단위 코드 수정
3. 리뷰별 커밋 생성
4. 커밋 push
5. 리뷰 reply 작성
6. 검증 기준 검사

---

# 6. Skill 작성 원칙

Skill을 작성할 때 다음 기준을 따른다.

### 1. 반복 작업만 Skill로 만든다

일회성 작업은 Skill로 만들 필요가 없다.

---

### 2. 작업 절차를 명확히 정의한다

AI가 판단하지 않도록 **단계적 작업 순서를 명시한다.**

---

### 3. 승인 요건을 명확히 정의한다

작업 완료 여부를 **객관적으로 검증 가능해야 한다.**

---

# 7. Skill 예시 (PR 리뷰 반영)

예시 Skill 목적

PR 리뷰 코멘트를 기반으로 코드 수정, 커밋 생성, 리뷰 답글 작성까지 자동 처리

예시 승인 요건

* 리뷰별 별도 커밋 생성
* 모든 커밋 push 완료
* 각 리뷰 코멘트에 reply 작성
* reply에 커밋 해시 포함
* PR 충돌 해결
* 린트 / 빌드 테스트 통과

이 Skill을 사용하면 PR 리뷰 반영 작업을 **일관된 방식으로 자동 처리**할 수 있다.

---

# 8. 핵심 정리

AI Skill은 다음 역할을 한다.

* 반복 작업 자동화
* 작업 절차 표준화
* 결과 검증 가능

따라서 Skill은 **프롬프트 관리 기능이 아니라 팀 개발 프로세스를 AI에 적용하는 방식**이다.


AI Skills

# 스모크 테스트 (Smoke Test)

## 정의

**기본 기능이 최소한 정상적으로 동작하는지 빠르게 확인하는 테스트**

> 용어 유래: 하드웨어 업계에서 장비 전원을 켰을 때 연기(smoke)가 나지 않으면 기본적으로 정상이라는 의미에서 시작됨

---

## 소프트웨어에서의 의미

새 빌드나 배포 후:
- 앱이 실행되는지
- 주요 기능이 크래시 없이 동작하는지

를 빠르게 확인하는 테스트

**핵심:** "이 빌드를 더 테스트할 가치가 있는지 확인하는 1차 테스트"

---

## 예시 (모바일 앱)

React Native 앱 기준 스모크 테스트 체크리스트:

| 항목 | 확인 내용 |
|------|----------|
| 앱 실행 | 정상 실행됨 |
| 로그인 | 가능 |
| 메인 화면 | 로딩됨 |
| API 호출 | 정상 |
| 앱 안정성 | 크래시 없음 |

---

## 테스트 종류 비교

| 테스트 | 목적 |
|--------|------|
| Smoke Test | 기본 동작 확인 |
| Unit Test | 함수 단위 테스트 |
| Integration Test | 모듈 간 동작 확인 |
| E2E Test | 실제 사용자 시나리오 테스트 |

---

## 실제 CI/CD 적용 흐름

새 빌드 생성 → Smoke Test 실행 → 통과 시 QA 테스트 진행



---

## 한 줄 요약

> "이 앱/빌드가 최소한 망가지지 않고 실행되는지 확인하는 빠른 테스트"

스모크 테스트란?

# 철학

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

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

커밋 컨벤션, 코드 리뷰 요청 방법, 코드 리뷰 방법

코드 리뷰

## 1. 철학 (Philosophy)

일은 신뢰를 증명하는 행위다.

우리는 시스템 위에서 자유롭게 일하며, 신뢰를 무너뜨리지 않는다.  
정리된 사고, 투명한 협업, 명확한 책임으로 신뢰를 만든다.  
우리의 일은 문제를 해결하고, 고객의 약속을 완성하는 과정이다.

---

## 2. 행동 원칙 (Principles)

1. **정리되지 않은 일은 시작하지 않는다.**  
- 맥락과 자료를 명확히 한 뒤 움직인다.  
- 혼란은 비용이고, 정리는 시작의 예의다.

2. **맥락을 이해하지 못한 일은 실행하지 않는다.**  
- '왜'가 없는 일은 방향을 잃는다.  
- 목적을 모르면 실행보다 이해를 택한다.

3. **책임은 혼자가 아니라 명확하게 진다.**  
- 문제를 공유하는 건 책임 회피가 아니라 해결의 일부다.  
- 다만 최종 책임자는 끝까지 확인한다.

4. **시스템 위에서만 자유가 작동한다.**  
- 질서는 자유를 막지 않는다.  
- 구조가 있어야 창의가 산다.

5. **숨김없는 소통이 곧 품질이다.**  
- 늦은 공유는 늦은 해결이다.  
- 감정보다 정보가 먼저다.

6. **문제는 '누가'가 아니라 '왜'에서 찾는다.**  
- 사람을 탓하지 않는다.  
- 프로세스를 고치고, 시스템을 개선한다.

7. **결과보다 과정을 신뢰한다.**  
- 완성은 과정의 축적이다.  
- 개선이 반복될 때 품질은 따라온다.

---

## 3. 실천 지침 (Practices)

### 1. 일은 '신뢰'를 쌓는 행위다
- 우리의 결과물은 곧 신뢰의 증거입니다.
- 약속한 일정을 지키는 것, 기획서대로 만드는 것, 에러 없는 코드를 제출하는 것 모두가 신뢰를 만드는 과정입니다.
- 한 번의 실수는 용서받을 수 있지만, 신뢰가 깨지면 회복하기 어렵습니다.

### 2. 일은 '문제 해결'이다 (작품 활동이 아니다)
- 우리는 아티스트가 아닌 기술 전문가입니다.
- 고객의 비즈니스 문제를 해결해주는 것이 목적입니다.
- 내 취향이나 판단이 아닌, 고객이 요청한 것이 정답입니다.

### 3. 일은 '커뮤니케이션'이다
- 말하지 않으면 아무도 모릅니다.
- 문제를 숨기는 것이 최악의 상황을 만듭니다.
- 15분 이상 혼자 고민하는 것은 비효율입니다.
- "모르겠습니다"는 부끄러운 말이 아니라, 해결의 시작입니다.

### 4. 일은 '확인'이다 (추측이 아니다)
- 기획서에 없으면 물어봅니다.
- 이해가 안 되면 확인합니다.
- 내 생각대로 만들지 않습니다.
- 추측의 99%는 틀립니다.

### 5. 일은 '완성'이다 (진행이 아니다)
- "다 만들었다" = "테스트까지 완료했다"
- 실행해 보아야 코드인 것입니다. 실행해 보지 않은 코드는 일을 하지 않은 것입니다.
- 마지막 1%를 채우는 것이 프로와 아마추어의 차이입니다.

### 6. 일은 '약속'이다
- 마감 기한은 가장 중요한 약속입니다.
- 일정을 길게 잡는 것은 부끄럽지 않지만, 약속을 못 지키는 것은 재앙입니다.
- 고객에게 함부로 "네"라고 즉답하지 않습니다.
- 근거 없는 약속은 거짓말과 같습니다.

### 7. 일은 '책임'이다
- 내가 만든 것의 1차 책임은 나에게 있습니다.
- 규칙을 따르지 않아 생긴 문제는 나의 책임입니다.
- 문제가 생겼을 때 빨리 공유하는 것도 책임입니다.

### 8. 일은 '성장'이다
- 리뷰는 공격이 아닌 성장의 기회입니다.
- 실수에서 배우고 재발을 방지하는 것이 성장입니다.

---

> **한 문장으로 정리하면:**
>
> *"일이란, 고객과의 약속을 신뢰를 기반으로 완성하고, 그 과정에서 투명하게 소통하며 책임지는 것이다."*

---

## 4. 결언

우리는 신뢰를 중심으로 일한다.

시스템은 우리를 묶는 것이 아니라, 서로를 믿게 하는 장치다.  
이 기준을 따르는 한, 누구도 통제받지 않는다.

ONBOARDERS WORK MINDSET (일 마인드셋)

> [원문](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가 아닙니다.

Wiki