SharedLedger Journey Part 1: From Zero to Phoenix

🌍 The Context: Berlin, New Life, New Needs

2025년 9월, 베를린으로 이사를 왔다. 새로운 도시, 새로운 생활, 그리고 파트너와 함께 관리해야 할 새로운 재정. EUR(유로)와 KRW(원화)를 동시 사용하게 되면서, 기존의 가계부 앱들은 우리의 니즈를 충족시키지 못했다:

• 다중 통화 지원 (EUR ↔ KRW real-time conversion)
• 공유 계좌 개념 (shared ledger for couples)
• 거래별 카테고리 분류
• 월간/연간 요약 및 분석

그리고 동시에, 나는 AI 코딩 도구 분야를 깊이 탐구하고 싶었다.

“그렇다면, 직접 만들어보면 어떨까? AI 도구와 함께.”

🤖 Why AI-Assisted Development?

이 프로젝트는 처음부터 AI 코딩 도구 실험을 염두에 두고 시작했다:

• Claude Code의 실제 프로젝트 적용 능력 테스트
• AI 도구의 강점과 한계 파악
• 효과적인 AI 활용 패턴 학습
• Elixir/Phoenix 생태계에서의 AI 도구 활용 가능성 검증

💡 Honest Expectations Setup

시작하기 전 알아야 할 것들:

이 프로젝트는 “AI가 모든 걸 완벽하게 만들어준“ 이야기가 아니다. 현실은:

• ✅ My Role: Architecture design, planning, decision making, extensive refactoring, fixing broken implementations
• 🤖 Claude Code’s Role: Code generation, boilerplate creation, initial feature implementation
• ⏰ Time Reality: ~30% planning, ~40% AI-assisted coding, ~30% refactoring/fixing what AI messed up

AI 도구는 강력하지만, 특히 Ash Framework 같은 특수한 프레임워크에서는 많은 수정과 개선이 필요했다. 이 시리즈는 그 현실적인 여정을 다룬다.

🔧 Technology Choices

Why Elixir?

이러나 저러나 Elixir는 나의 favorite language이고, 최근에는 업무에서 다른 언어들을 쓰고 있다보니, Elixir 프로젝트를 하고 싶은 욕구가 더 많이 생기더라. 스스로 Elixir 전문가라고 생각하고 있기 때문에, Claude Code가 만드는 Elixir 코드를 내가 얼마나 잘 검증할 수 있을지도 궁금했다.

Why Phoenix LiveView?

사실 아직도 복잡한 SPA 수준의 서비스를 Phoenix LiveView로 만들 수 있을지 잘 모르겠다. 불편한 부분이 많고, 그만큼 활발하게 변화가 이뤄지고 있어서, 계속 쫓아가는 입장이다. 언젠가 LiveView가 완벽하게 프론트엔드를 대체할 날이 올지 정말 궁금하다.

Why Ash Framework?

Ash Framework도 최근 정말 핫하다고 느꼈는데, 그만큼 러닝커브도 크다고 느끼고 있다. 언제나 느끼는 거지만 강력한 프레임워크를 쓴다는 것은 그만큼 자유를 포기한다는 뜻이다. 이 프로젝트에서는 특히 이 Ash를 Claude Code가 얼마나 잘 다룰수 있을지가 궁금했다.

Key Decision: PostgreSQL (not ETS/SQLite)

• Initial plan: SQLite for MVP
• Reality: Switched to PostgreSQL early
• Reason: Production-ready from day one

🚀 Project Initialization

Day 1: Setting Up

1. Documentation phase with Claude (17+ files, ~5,500 lines):

   Architecture Documents (in docs/architecture/):

   • DOMAIN_MODEL.md (1,066 lines) - 4개 domain 정의 (Identity, Accounts, Ledger, Currency)
   • UI_COMPONENTS.md (1,026 lines) - Atomic Design 기반 완전한 UI 스펙
   • API_SPECIFICATION.md (645 lines) - LiveView event contracts
   • DATABASE_DESIGN.md (489 lines) - 전체 스키마 구조
   • ASH_FRAMEWORK_ANALYSIS.md (355 lines) - Ash 프레임워크 평가 및 사용 전략
   • SYSTEM_ARCHITECTURE.md (292 lines) - 레이어 아키텍처 및 패턴

   Project Documents (in docs/):

   • REQUIREMENTS_SPECIFICATION.md (815 lines) - 기능/비기능 요구사항
   • PROJECT_PLAN.md (572 lines) - MVP → Phase 2 → Phase 3 로드맵
   • TECHNICAL_SPECIFICATION.md - 구현 세부사항
   • CLAUDE.md (229 lines) - AI 어시스턴트 가이드
   • Plus: PROJECT_STATUS, DEPLOYMENT_OPERATIONS_GUIDE, DATA_FLOW_INTEGRATION

2. Project initialization:

   • mix phx.new shared_ledger
   • mix igniter.install for Ash Framework and dependencies

📝 First Lesson with Claude Code

Day 1: 완벽한 계획

실제 mix new 명령을 실행해 코드를 생성하기 전에, 문서를 제대로 만드는 것에 집중했다. 회사 프로젝트를 하며 쌓은 노하우로 필요한 핵심 문서들을 역시 Claude를 이용해 만들기 시작했다. 여기서 제대로 할수록, 뒤에 들어가는 불필요한 노력이 줄어든다.

문서를 잘 만들면:

• ✅ AI가 내 아키텍처 의도를 이해한다
• ✅ 일관된 패턴으로 코드를 생성한다
• ✅ 같은 실수를 반복하지 않는다

하지만 함정이 있었다…

Day 2: 현실과의 충돌

# Day 1에 완벽하게 계획한 코드
changeset = Ash.Changeset.for_action(User, :create, %{})
form = to_form(changeset)  # 🔥 Protocol error!

에러 메시지: Protocol Phoenix.HTML.FormData not implemented for Ash.Changeset

완벽한 문서가 있어도, Ash Framework의 특수한 integration 이슈는 막을 수 없었다. 이날 새로운 문서들이 생겼다:

• DEVELOPMENT_CONVENTIONS.md - Ash+Phoenix 패턴
• ADR-005: Ash-Phoenix Form Integration - 왜 이렇게 했는지

두 종류의 문서:

1. Proactive (Day 1) - 문제를 예방하는 문서
2. Reactive (Day 2) - 문제를 해결하고 기록하는 문서

AI Agent는 끊임없이 내가 원하는 방향과 다른 정보를 의도치 않게 심기 때문에, 문서를 면밀히 검토하고 계속 업데이트할 필요가 있었다.

교훈: 문서는 one-and-done이 아니다. 살아있는 문서여야 한다.

🏗️ Architecture Planning

Domain Contexts

Initial planning led to 4 main contexts:

1. Identity - Users, authentication, sessions
2. Accounts - Shared accounts, memberships, roles
3. Ledger - Transactions, categories, summaries
4. Currency - Exchange rates, conversions

┌─────────────────────────────────────────────────┐
│                   Phoenix UI                     │
│              (LiveView Components)               │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│                Domain Layer                      │
│  Identity  │  Accounts  │  Ledger  │  Currency  │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│              Ash Resources Layer                 │
│    (Declarative definitions + Actions)          │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│                  PostgreSQL                      │
└─────────────────────────────────────────────────┘

🤔 Architecture Decision Challenges

초기 상태: Elixir는 자신 있었지만, domain modeling과 relationship 설계는 고민이 많은 부분이라, 이번엔 Claude의 구체적이고 종합적인 설계를 따라보기로 했다.

핵심 실수: “설명이 논리적이니까 맞겠지“ 하며 비판 없이 수용.

주요 사례들:

• 4-domain structure → Week 5에 domain boundary refactoring
• Many-to-many + RBAC → manage_relationship 이해 없이 구현 → 2주 디버깅
• SQLite → PostgreSQL 강제 migration (Day 7)
• 403 Forbidden → 404 NotFound (security 이슈)

패턴: Claude 제안 → “그럴듯” → 구현 → 문제 발견 → refactoring

Time Cost: Architecture review 10시간 vs. 나중에 고치기 3-4주 (1:20~30 ratio)

교훈: AI는 패턴을 안다. 하지만 내 문제, trade-offs, security implications는 모른다. “AI는 옵션 제시. 결정은 내가.”

→ Part 2에서 domain 설계 세부 사항 다룸

📋 Initial Feature Planning

MVP Scope (Week 1 Planning)

Must Have:

• ✅ User authentication (email/password)
• ✅ Create/join shared accounts
• ✅ Add transactions (amount, category, date, note)
• ✅ Multi-currency support (EUR, KRW)
• ✅ Basic transaction list view
• ✅ Monthly summary

Nice to Have (Later):

• ❌ Budget tracking
• ❌ Recurring transactions
• ❌ Advanced analytics
• ❌ Mobile app (PWA instead)

💡 Lesson: Pattern Pollution

AI와 작업하면서 가장 위험했던 패턴: 나쁜 코드가 눈덩이처럼 커지는 것

시나리오: 큰 feature 요청 (500줄) → 대부분 잘 작동 → 귀찮아서 세부 리뷰 생략 → 10줄의 잘못된 코드 숨어있음 → Claude가 그걸 학습 → 다음 feature에서 반복.

Real Example:

• Week 1: Transaction LiveView에서 Ash.Query 직접 사용 (리뷰 안 함)
• Week 2-3: Category, Summary LiveView → 같은 패턴 복사
• Week 5: git grep "Ash.Query" → 12개 파일 발견 → 2주 refactoring

또 다른 예: Money 대신 Decimal 사용 → 모든 calculation에 확산 → Currency 정보 손실.

핵심:

• “작동 ≠ 옳음”
• 한 번의 실수 = 12번의 버그
• Review 30분 vs. Refactoring 2주 (1:40 ratio)

해결:

1. 큰 feature도 세부 리뷰 필수
2. 잘못된 패턴 즉시 수정 (나중에 ✗)
3. Anti-patterns를 CLAUDE.md에 기록
4. 주기적 audit (git grep 금지 패턴)

→ Part 4에서 refactoring 상세히 다룸

🎯 Documentation-Driven Development

One of the best decisions: Creating comprehensive documentation for Claude Code.

Files created:

• CLAUDE.md - Project-specific guidelines
• AGENTS.md - Phoenix/LiveView/Elixir rules (later)
• ASH_DEVELOPMENT_GUIDE.md - Ash framework patterns
• ASH_LIVEVIEW_STRICT_RULES.md - Quick checklist

📝 Why This Mattered

ROI: 문서 작성 12-16시간 vs. 절약 30-40시간 (약 2-3배)

효과:

• Claude가 일관된 패턴 따름
• 같은 실수 반복 줄어듦
• 멀티태스킹 가능 (문서가 나를 대신)

Trade-offs:

• 문서 작성 시간 많이 듦
• 계속 업데이트 필요
• Claude가 가끔 문서 무시함

결론: 복잡한 프레임워크 (Ash, LiveView)는 문서 필수. 간단한 프로젝트는 불필요.

🔄 Development Workflow Setup

Tools & Environment

# Docker for PostgreSQL
docker-compose up -d postgres

# Development commands (Makefile)
make dev-setup  # First time
make dev        # Daily use
make test       # Run tests
make format     # Code formatting

🤔 Workflow with Claude Code

확립된 패턴:

1. Feature 시작: 브랜치 생성 → Claude에게 context 제공 (DOMAIN_MODEL.md 등)
2. 작업 중: 즉시 리뷰, 패턴 위반 시 중단, 각 단계 compile 확인
3. Iteration: 평균 3-4번 (Ash 직접 사용 → Domain 함수 → Authorization → Error handling)
4. Commit: Claude 제안 message 거부, 직접 작성

역할 분담:

• Claude: Boilerplate, 반복 CRUD, test 초안
• 나: Architecture 결정, 복잡한 비즈니스 로직

핵심: Pair programmer로 쓰되, final decision은 내가.

📊 First Week Results

By the end of first week (Sep 11-18):

✅ Project initialized
✅ Ash framework integrated
✅ Basic domain structure defined
✅ SQLite setup (later migrated to PostgreSQL)
✅ Initial documentation written
✅ Core features implemented (but needed fixes)
⚠️  Many compilation errors to resolve

Git commits tell the story:

dd3de03 - docs: Add comprehensive Ash framework implementation
4377a84 - docs: Add complete Ash framework architecture
b010fc3 - feat: Implement core MVP features with Ash
394878a - feat: Implement Phoenix LiveView UI

💡 Key Insight

Planning이 시간을 절약했다:

• 문서 먼저: 48시간 총 투자
• 문서 없이 (추정): 60시간+ (architecture 리팩토링, 반복 실수)
• 절약: ~20%

더 중요한 것: 올바른 구조, 일관된 패턴, 적은 technical debt.

하지만: 문서가 완벽하게 막진 못함. Week 5-6에 26개 refactoring commits 필요. AI 생성 코드는 여전히 리뷰와 refactoring 필수.

🎬 What’s Next?

In Part 2, we’ll dive into:

• Implementing the four domain contexts with Ash
• Resource definitions and relationships
• Authorization setup (RBAC)
• Testing in IEx before touching LiveView
• Lessons learned about guiding Claude with Ash patterns