AI와 함께 아이디어 기획서를 개발 설계서로 발전

- **도구**: Claude Code (VSCode 확장)
- **모델**: Claude Sonnet 4.6
- **방법론**: PDCA + bkit 플러그인

## 1단계: 아이디어 → 사업 기획안

통합 가이드라인 문서 하나를 들고 Claude Code에게 요청했다.

> *"통합 가이드라인을 참고하여 가상자산 세무 플랫폼의 기획안을 작성해줘"*

한 번에 완성본이 나오지는 않았다. 초안이 나온 뒤 검토 과정에서 두 가지 문제가 발견됐다.

**문제 1 — IP와 오픈소스 충돌:** 기획안 §4.1에서는 "오픈소스로 투명하게 공개"한다고 했으면서, §8에서는 "핵심 IP 100% 자체 보유"라고 했다. 논리적 모순이었다. → *"연산 방법론은 문서로 투명하게 공개하되, 핵심 IP는 자체 보유"*로 수정.

**문제 2 — 세무사법 위반 리스크:** 프리미엄 플랜에 "세무 신고 대행"이라는 표현이 들어 있었다. 세무사 자격 없이 신고를 대행하면 세무사법 위반이다. → *"세무 신고 지원 (파트너 세무사 연결)"*로 수정.

이렇게 사업 기획안 완성본(`03#`)이 만들어졌다.

---

## 2단계: 기획안 → PDCA 개발 문서

사업 기획안이 있다고 개발이 시작되지는 않는다. 개발팀이 바로 실행할 수 있으려면 세 가지 문서가 필요하다.

- **Plan** — 무엇을 만들 것인가 (요구사항, 리스크, 아키텍처 방향)
- **Design** — 어떻게 만들 것인가 (타입 정의, API 명세, UI 설계, 파일 구조)
- **Do** — 어떤 순서로 만들 것인가 (구현 순서, 핵심 코드 패턴)

bkit의 PDCA 스킬을 순서대로 실행했다.

```
/pdca plan 코인택스
/pdca design 코인택스
/pdca do 코인택스
```

각 명령어가 이전 문서를 참조하면서 다음 문서를 생성했다. 그런데 여기서 가장 중요한 일이 벌어졌다.

---

## 3단계: 도메인 지식으로 AI를 교정하다

문서가 생성될수록 세금 계산 로직의 오류가 드러났다. 세 번의 핵심 교정이 있었다.

### 교정 1 — 총 양도차익 계산 순서

초안의 `TaxCalculationResult`는 이런 구조였다.

```typescript
totalGain = totalRevenue - totalCost  // 전체 양도가액 - 전체 취득원가
```

사용자가 지적했다.

> *"코인별로 양도가액에서 취득가액을 빼서 코인별 양도차익을 구하고, 그 후에 모든 코인의 양도차익을 더하는 순서가 맞습니다."*

수정 후:

```typescript
// ① 코인별 양도차익 산출 (먼저 확정)
coinBreakdown = portfolio.map(item => gain = saleRevenue - acquisitionCost)

// ② 총 양도차익 = 코인별 합산 (파생)
totalGain = coinBreakdown.reduce((s, c) => s + c.gain, 0)
```

두 방식은 수학적으로 같은 결과를 낼 수 있지만, **전자는 코인별 검증이 불가능**하다. 코인별 양도차익 내역서를 제출해야 하는 세무 신고 실무에서는 후자가 맞다.

### 교정 2 — 코인별 세액 제거

`CoinTaxDetail` 인터페이스 주석에 "코인별 세액 상세"라는 표현이 남아 있었다. 사용자가 지적했다.

> *"코인별 세액은 필요가 없는 것이니 확인하고 수정해줘"*

세액은 전체 합산 양도차익에서 기본공제(250만 원)를 뺀 뒤 **1회만** 계산한다. 코인별로 세액을 나누면 기본공제가 중복 적용되는 오류가 생긴다. `taxAmount` 필드를 삭제하고 주석을 명확히 수정했다.

```typescript
// 코인별 양도차익 상세 (세액은 전체 합산 후 1회만 계산 — 코인별 세액 없음)
interface CoinTaxDetail {
  gain: number  // 코인 양도차익
  // taxAmount 없음
}
```

### 교정 3 — 거래소 간 코인 이동(TRANSFER) 처리

가장 중요한 교정이었다.

> *"코인은 매입한 거래소에서 꼭 매도하는 것이 아닙니다. 업비트에서 매수 후 빗썸으로 이동하여 매도하는 경우도 있습니다."*

처음엔 거래 타입이 `'BUY' | 'SELL'` 뿐이었다. 이 상태에서 거래소 간 이동(출금/입금)을 처리하면 매도로 잘못 분류될 수 있다. `'TRANSFER'` 타입을 추가하고 합산 로직에서 제외했다.

```typescript
type Transaction = {
  type: 'BUY' | 'SELL' | 'TRANSFER'  // TRANSFER = 이동, 세액 계산 제외
}

function aggregateSources(item: CoinPortfolioItem): Transaction[] {
  return item.sources
    .flatMap(s => s.transactions)
    .filter(tx => tx.type !== 'TRANSFER')  // 이동 내역 제외
    .sort((a, b) => a.date.getTime() - b.date.getTime())
}
```

업비트에서 매수 → 빗썸으로 이동 → 빗썸에서 매도한 경우:
- 업비트 매수: BUY → 취득원가에 포함 ✅
- 이동 내역: TRANSFER → 제외 ✅
- 빗썸 매도: SELL → 양도가액에 포함 ✅

---

## 4단계: 문서 간 일관성 최종 점검

세 문서(Plan, Design, Do)가 완성된 뒤 최종 점검에서 두 가지 불일치가 더 발견됐다.

**불일치 1 — 오타:** 사업 기획안 §5 Phase 2에 "제휴 기관**진** 연동"이라는 오타가 있었다. → "제휴 기관 연동"으로 수정.

**불일치 2 — FileParser 레이어 분류:** Design 문서의 레이어 정의표(§9.2)에서 `FileParser`의 경로와 레이어가 다른 위치의 파일 구조(§11.1)와 달랐다.

이때 단순히 두 표를 맞추는 것이 아니라 **레이어 정의 원칙(§9.1)**을 먼저 확인했다.

> §9.1: Infrastructure = 파일 파싱, BaaS API, PDF → `src/lib/`

FileParser는 SheetJS를 통한 외부 파일 I/O 어댑터로, 명백히 Infrastructure다. §11.1의 파일 구조가 틀린 것이었다. §9.2, §11.1, §11.2 그리고 Do 문서의 경로를 모두 `src/lib/file-parser/`로 통일했다.

---

## 최종 산출물

```
기획서 만들기/
├── 03# [완성본] 코인택스 사업 기획안.md     ← 비즈니스 문서
├── 04# 코인택스 Plan (개발 계획).md         ← 요구사항·리스크·아키텍처
├── 05# 코인택스 Design (설계 명세).md       ← 타입·API·UI·파일 구조
└── 06# 코인택스 Do (구현 가이드).md         ← 27단계 구현 순서·핵심 코드
```

| 문서 | 핵심 내용 |
|------|-----------|
| 사업 기획안 | 시장 분석, 4헌장 원칙, 3Phase 로드맵, 수익 모델 |
| Plan | FR-01~FR-13 기능 요구사항, 7개 리스크 대응 전략 |
| Design | TypeScript 타입 15개, API 2종, 4-Step 위자드 UI, 27개 파일 구조 |
| Do | Phase별 구현 순서, aggregateSources·calculateTax·detectDuplicates 핵심 코드 |

---

## 다음 단계

문서 완성은 개발의 출발점이다. 이제 남은 것은 실제 코드다.

```bash
pnpm create next-app@latest cointax --typescript --tailwind --app --src-dir
```

코드가 완성되면 `/pdca analyze 코인택스`로 Gap 분석을 돌린다. 설계대로 구현됐는지 자동으로 점검하고, 90% 이상 일치하면 완료 보고서를 생성한다.

아이디어에서 설계서까지는 AI와 함께 하루 만에 왔다. 설계서에서 서비스까지의 여정이 시작된다.

## 이 과정에서 배운 것

**1. AI는 초안을 빠르게 만들고, 사람은 도메인 지식으로 교정한다**

세 번의 핵심 교정은 모두 세금 도메인 지식에서 나왔다. AI가 수학적으로 맞는 코드를 짰어도, 세무 실무 맥락에서는 틀릴 수 있다. AI의 속도와 사람의 전문성이 조합될 때 좋은 결과가 나온다.

**2. 문서 간 불일치는 반드시 발생한다 — 점검 단계가 필수다**

Plan → Design → Do로 문서가 쌓일수록 초기에 정한 내용이 나중 문서에 반영되지 않는 경우가 생긴다. PDCA의 Check 단계가 코드뿐 아니라 **문서 간 일관성**에도 필요한 이유다.

**3. 레이어 분류는 정의에서 출발해야 한다**

FileParser 경로 불일치를 해결할 때 "어디에 많이 있냐"가 아니라 "§9.1 레이어 정의가 무엇이냐"로 판단했다. 아키텍처 결정은 관례가 아니라 원칙에서 출발해야 일관성이 유지된다.

**4. '구현 가이드'가 있으면 개발자가 바로 시작할 수 있다**

Do 문서의 27단계 구현 순서와 핵심 코드 패턴이 있으면, 개발자는 설계를 재해석할 필요 없이 바로 코드를 작성할 수 있다. 기획자와 개발자 사이의 번역 비용이 줄어든다.