🌑 어둠 속으로: Soulbound Codex

Source: Dev.to

배경

Kiroween은 AWS가 주최하는 할로윈 테마 해커톤으로, Kiro라는 AI 코딩 에이전트의 힘을 보여주기 위해 마련되었습니다. 도전 과제는 한 달 안에 야심 차고 창의적인 무언가를 만들기였습니다.

저에게는 AI, 고딕 미학, 멀티‑모듈 UI 아키텍처, 고급 에이전트 워크플로우를 처음으로 결합하는 미지의 세계에 뛰어드는 것이었습니다. 그 결과물은 Soulbound Codex라는, 완전한 생산성 스위트를 으스스하고 몰입감 있는 경험으로 바꾼 프로젝트였습니다.

내가 만든 것: Soulbound Codex

Kiroween은 어두운 테마의 생산성 플랫폼으로, 다음과 같은 기능을 제공합니다:

• ✍️ Ghost Writer – 실시간 AI 글쓰기 제안
• 📖 Necronomicon Notes – 고대의 움직이는 두루마리 안에서 글쓰기
• ⚰️ Graveyard Dashboard – 작업이 무덤돌이로 변하고 물리와 의식 애니메이션 적용
• 🔮 Terminal Tarot – Git 커밋을 분석해 타로 리딩 생성
• 🌕 Moon Phase Calendar – 천문학적 정확도로 시간 추적
• 🕸️ Ambient soundscapes와 고딕 UI가 분위기 있고 마법 같은 경험 제공

모든 것은 다음 기술로 구동됩니다:

React, TypeScript, Vite, CSS Modules, Firebase, OpenRouter AI, and Kiro’s spec‑driven development workflow.

기술적 성과

• 공유 상태와 오프라인‑우선 설계를 갖춘 완전한 멀티‑모듈 React 아키텍처
• NVIDIA Nemotron + OpenRouter 백업을 활용한 AI 글쓰기 어시스턴트
• 브라우저 내에서 직접 동작하는 isomorphic-git 기반 Git 점술 엔진
• Firebase를 이용한 클라우드 동기화(인증, 데이터베이스, 스토리지)
• 맞춤형 고딕 애니메이션, 파티클 효과, 양피지 렌더링
• 파워 유저를 위한 키보드‑드리븐 내비게이션
• 즉시 전환 가능한 테마 엔진
• 노트와 작업을 위한 import/export 시스템
• 모든 모듈에 레이어링된 접근성 향상

단순히 테마 UI가 아니라 실제 생산성 플랫폼입니다.

Kiro가 어떻게 도움을 줬는가

Kiro는 단순한 도구가 아니라 개발 파트너 역할을 했습니다.

Spec‑Driven Development

• 모든 요구사항, UX 동작, 아키텍처 패턴을 .kiro/specs에 기술했습니다.
• Kiro는 이 스펙을 깔끔하고 모듈화된 코드로 변환했으며, 재작업이나 모호함이 없었습니다.

Steering Docs

• 시각적 스타일 일관성, AI 응답 톤, 코딩 컨벤션, 아키텍처 경계를 관리했습니다.

Agent Hooks

• 다음과 같은 자동화 워크플로우를 구현했습니다:
  • Ghost Writer의 컨텍스트 추출
  • 테스트 스텁 자동 생성
  • 문장 완성 트리거
  • Terminal Tarot용 분석 파이프라인

새로운 Kiro 기능

• 특성 기반 테스트로 기능 스펙을 구현과 대조 검증
• 언제든지 Kiro의 코드 변경을 되돌릴 수 있는 체크포인트
• 터미널 안에서 커스텀 에이전트를 실행하는 Kiro CLI
• 중앙화된 스펙 + 스티어링 관리가 가능한 팀 기반 워크플로우

Kiro 없이 Kiroween을 만든다면 몇 주가 아닌 몇 달이 걸렸을 것입니다.

마주한 장애물

• ⏳ 시간 압박 – 업무, 일상, 거대한 멀티‑모듈 프로젝트를 동시에 진행; 어느 날은 30–60분만 코딩할 수 있었습니다.
• 🧩 복잡한 기능 상호작용 – 노트, 작업, AI 제안, 타로 리딩이 모두 공유 전역 상태, 모듈 간 내비게이션, 오프라인 영속성, 고성능을 요구했습니다.
• 👻 UI 정밀도 – 유령 애니메이션, 양피지 효과, 달 단계는 세심한 튜닝이 필요했습니다.
• 🔌 AI 통합 예측 불가능성 – 모델마다 동작이 달라 캐싱, 재시도, 백업 로직을 직접 구현해야 했습니다.
• 🌐 브라우저 내 Git 분석 – 서버 없이 로컬에서 커밋을 파싱하는 것이 매우 어려웠습니다.

각 장애물은 프로젝트를 한 단계 끌어올렸습니다.

개발 일정 (요약)

Day 1–3: 기본 구축

• 핵심 React 아키텍처, 내비게이션, 테마 엔진, 노트 스캐폴드, 작업 시스템 프로토타입

Day 4–6: 기능 확장

• Ghost Writer AI 통합, Graveyard Dashboard 애니메이션, Moon Phase 캘린더, 마크다운 에디터

Day 7–10: 고급 시스템

• Git 커밋 분석 엔진, 타로 생성 로직, AI 캐싱 + 백업, 클라우드 동기화, 인증

Day 11–14: 마무리 및 안정화

• 파티클 효과, 키보드 단축키, import/export, 접근성, 최종 버그 수정, 문서화

결과적으로 Kiroween은 4개의 완전한 모듈, 수십 개의 기능, 테스트, 그리고 일관된 UX를 갖추게 되었습니다.

배운 점

• 💡 AI‑보조 개발은 새로운 패러다임 – AI는 개발자를 증폭시켜, 몇 주 걸리던 보일러플레이트 작업을 몇 분 안에 해결합니다.
• 🧠 스펙이 그 어느 때보다 중요 – 명확한 스펙 = 완벽한 코드 생성; 모호한 스펙 = 혼란.
• ⚙️ 오프라인‑우선 아키텍처는 과소평가됨 – 오프라인을 먼저 설계하고, 동기화를 두 번째로 하면 모든 것이 더 견고해집니다.
• 🎨 미학은 기능적 힘을 가짐 – 아름다운 생산성 도구는 사용자를 더 오래 머무르게 합니다.
• 🪦 의식은 루틴을 넘어섬 – 작업이 “땅에 가라앉는” 느낌은 체크박스가 줄 수 없는 감정적 마무리를 제공합니다.

마무리 생각

Kiroween을 만드는 과정은 등불을 든 채 어두운 숲을 걷는 듯했습니다—각 발걸음은 Kiro가 비추지만, 길은 언제나 신비로 가득했습니다. 이 경험을 통해 저는:

• AI로 복잡한 소프트웨어를 빠르게 구축하는 방법
• 디자인이 사용자 감정에 미치는 영향
• 압박 속에서 계획하고 구조화하며 배포하는 방법

무엇보다도 Kiroween은 생산성 도구가 지루할 필요가 없으며, 분위기 있고 마법적이며 깊이 있는 개인 경험이 될 수 있음을 보여주었습니다. 일상 작업을 의식으로 바꾸고 싶다면, Kiroween이 바로 그 해답입니다.