# Augmented Coding Principles

## ⚠️ REMINDER: 한국어로 응답하세요!

All responses must be in Korean. Check `critical.md` for details.

Based on Kent Beck's approach: https://tidyfirst.substack.com/p/augmented-coding-beyond-the-vibes

## Philosophy: Beyond Vibe Coding

### Vibe Coding vs Augmented Coding

- **Vibe Coding**: Don't care about code, only behavior. Feed errors back to AI hoping for fixes.
- **Augmented Coding**: Care about code quality, complexity, tests, and coverage. Same value system as hand coding—tidy code that works. You just don't type much of it.

**We practice Augmented Coding**: High standards for AI-generated code, same as hand-written code.

---

## TDD Cycle (Strict Adherence)

Follow the **Red → Green → Refactor** cycle religiously:

1. **Red**: Write a failing test that defines a small increment of functionality
2. **Green**: Implement the minimum code needed to make the test pass
3. **Refactor**: Improve structure only after tests are passing

### Core Rules

- Write one test at a time
- Make it pass with minimal code
- Run all tests after each change
- Never skip the refactor step

### Project-Specific TDD Strategy

#### ESLint 규칙 검증 (Test-First TDD)

ESLint 설정 변경 시 TDD 적용:

**Workflow:**

1. 검증할 코드 예제 작성
   - 규칙을 위반하는 코드
   - 규칙을 준수하는 코드
2. 예상되는 ESLint 결과 정의
3. ESLint 규칙 추가/수정
4. 실제 프로젝트에서 테스트
5. 규칙 미세 조정

**예제:**

```javascript
// 1. 테스트 케이스 작성
// bad.js - 규칙 위반 (에러 발생 예상)
function foo() {
  return 'bar';
}

// good.js - 규칙 준수 (에러 없음)
const foo = () => 'bar';

// 2. ESLint 규칙 추가
'no-restricted-syntax': [
  'error',
  {
    selector: 'FunctionDeclaration',
    message: 'Function declarations are not allowed. Use arrow functions instead.'
  }
]

// 3. 검증
// bad.js → ✗ 에러 발생
// good.js → ✓ 통과
```

---

## Tidy First 접근법

**핵심 원칙**: 구조적 변경과 동작 변경을 분리. 절대 섞지 말 것.

### 두 가지 변경 유형

#### 1. 구조적 변경 (Tidy First)

동작 변경 없이 코드 재구성:

- 규칙 재정렬 및 그룹화
- 주석 개선
- 중복 규칙 제거
- 포맷팅 수정

**검증**: 동일한 ESLint 동작 유지—기존 프로젝트에서 동일한 결과

#### 2. 동작 변경

실제 ESLint 동작 수정:

- 새 규칙 추가
- 규칙 엄격도 변경 (warn → error)
- 규칙 옵션 수정
- 플러그인 추가/제거

### 워크플로우 규칙

두 유형의 변경이 모두 필요한 경우:

1. 구조적 변경을 먼저 수행
2. 구조적 변경을 별도로 커밋
3. 그 다음 동작 변경 수행
4. 동작 변경을 별도로 커밋

**절대 같은 커밋에 섞지 말 것**

**예제:**

```bash
# 1단계: 구조적 변경 (Tidy)
git commit -m "refactor: 공백 관련 규칙을 하나의 섹션으로 그룹화"

# 2단계: 동작 변경 (Behavior)
git commit -m "feat: max-len 규칙을 80자로 강제"
```

---

## 커밋 규율

### 커밋 조건:

1. ✅ ESLint 설정이 유효함 (구문 오류 없음)
2. ✅ 실제 프로젝트에서 테스트 완료
3. ✅ 변경이 단일 논리적 작업 단위를 나타냄
4. ✅ 커밋 메시지가 명확히 구조적 또는 동작 변경 명시
5. ✅ Changeset 생성 (버전 변경 필요 시)

### 커밋 메시지

- **구조적**: `refactor: import 규칙을 별도 섹션으로 분리`
- **동작적**: `feat: 화살표 함수 강제 규칙 추가`
- **수정**: `fix: no-restricted-syntax 규칙 정규식 오류 수정`

크고 드문 커밋보다 작고 빈번한 커밋 선호

---

## AI 모니터링 체크포인트

AI를 주의 깊게 관찰하고 다음을 발견하면 개입:

### 🚨 경고 신호 (즉시 AI 중단)

1. **불필요한 복잡성**: 간단한 규칙을 과도하게 복잡하게 작성
2. **요청하지 않은 변경**: 요청하지 않은 규칙 추가/수정
3. **주석 삭제**: 기존 한국어 주석 제거
4. **참조 번호 제거**: `#숫자` 형식의 참조 제거
5. **중복 추가**: 이미 정의된 규칙 재정의

### ✅ 좋은 AI 동작

- 정확한 지시 준수
- 기존 코드 스타일 유지
- 한국어 주석 작성
- 참조 번호 보존
- 불확실할 때 명확화 요청

### 개입 전략

중간 결과를 지속적으로 검토:

- 각 AI 응답 후 변경사항 확인
- AI가 정확히 요청한 것을 했는지 검증
- 경로를 벗어나면 중단하고 재지시
- 구체적인 다음 단계 제안

---

## 코드 품질 표준

### 핵심 원칙 (SOLID)

- **단일 책임**: 각 규칙은 하나의 코드 스타일만 강제
- **개방/폐쇄**: 프로젝트별 확장은 허용, 기본 규칙은 수정 최소화
- **명확한 의도**: 규칙의 목적이 주석으로 명확히 표현됨
- **최소 의존성**: 필요한 플러그인만 사용
- **일관성**: 모든 규칙이 동일한 형식과 스타일 유지

### 품질 메트릭

- **중복 제거**: DRY (Don't Repeat Yourself) 철저히 적용
  - 같은 규칙을 여러 번 정의하지 않음
- **의도를 명확히 표현**: 주석이 규칙의 목적을 드러냄
- **호환성 유지**: React 19/Next.js 15와 호환
- **최소 설정**: 필요한 규칙만 포함
- **가장 간단한 해결책**: "작동할 수 있는 가장 간단한 설정은 무엇인가?"

### ESLint 설정 표준

- **주석**: 모든 규칙에 한국어 설명 주석
- **참조 번호**: Wishket 코드 스타일 가이드 참조 번호 유지
- **그룹화**: 관련 규칙을 카테고리별로 그룹화
- **일관성**: 동일한 형식과 들여쓰기 사용
- **테스트**: 실제 프로젝트에서 검증

---

## 리팩토링 가이드라인

### 리팩토링 시기

- **Green** 단계에서만 (설정이 유효하고 테스트 통과)
- 새 규칙 추가 후
- 중복을 발견했을 때
- 의도가 불명확할 때

### 리팩토링 방법

1. **한 번에 하나의 변경**: 단일 리팩토링 작업
2. **각 단계 후 검증**: ESLint 설정이 여전히 유효한지 확인
3. **명확성 우선**: 중복 제거, 주석 개선, 그룹화

### 일반적인 리팩토링

- 규칙 재그룹화 (카테고리별)
- 주석 개선
- 중복 규칙 제거
- 규칙 순서 재정렬
- 매직 값을 상수로 교체

---

## 예제 워크플로우

### 새 ESLint 규칙 추가

#### 1단계: 테스트 케이스 작성 (Red)

```javascript
// test-cases/arrow-functions/bad.js
function add(a, b) {
  return a + b;
}

// test-cases/arrow-functions/good.js
const add = (a, b) => a + b;
```

#### 2단계: 규칙 추가 (Green)

```javascript
// index.js
'no-restricted-syntax': [
  'error',
  {
    selector: 'FunctionDeclaration',
    message: 'Function declarations are not allowed. Use arrow functions instead.'
  }
]
```

#### 3단계: 테스트 검증

실제 프로젝트에서 ESLint 실행:
- `bad.js` → ✗ 에러 발생 확인
- `good.js` → ✓ 통과 확인

#### 4단계: 리팩터 (필요시)

주석 추가, 규칙 그룹화 등

#### 5단계: 커밋

```bash
git commit -m "feat: 화살표 함수만 사용하도록 강제하는 규칙 추가"
```

#### 6단계: Changeset 생성

```bash
yarn changeset
# minor 선택
# "화살표 함수 강제 규칙 추가" 입력
```

---

## 프로젝트 규칙과의 통합

이 파일은 AI와 **어떻게** 코드를 작성하는지 정의합니다.

참고 문서:

- `core.md` - PLAN/ACT 모드와 커뮤니케이션 규칙
- `project.md` - ESLint 패키지 구조, 퍼블리싱 워크플로우
- `critical.md` - 절대 위반하면 안 되는 규칙

---

**기억하세요**: AI와 프로그래밍하는 것도 여전히 프로그래밍입니다. 시간당 더 많은 중요한 결정을 내리고, 지루한 결정은 줄입니다. 아키텍처, 디자인, 품질에 집중하고—AI가 타이핑을 처리하게 하세요.