이 기사에 대하여

2026년 7월 7일, 이벤트 책갈피 앱 「Yui(栞)」를 정식 출시했습니다. 여행·이벤트 계획을 AI와 동료와 함께 "한 권의 책갈피"로 만들 수 있는 웹 서비스입니다.

이 프로덕트는 요구사항 정리부터 아키텍처 설계·구현·테스트·인프라 구축, 그리고 상표 등록 등의 법무 관련 업무까지, 거의 모든 페이즈를 AI 에이전트(주로 Claude Code)와 협업하여 개발했습니다. 이 기사에서는 기술적인 면에 초점을 맞추어, 실제 워크플로우와 운용 노하우, 주의해야 할 점을 공유합니다.

사업 측면의 AI 활용을 포함한 전체 스토리는 note 버전에, 서비스 자체의 소개는 공식 사이트에 있습니다.

기술 스택

AI 모델의 구분 사용 (비용 설계)

앱 내의 AI 기능은 처리의 복잡도에 따라 모델을 나누고 있습니다.

Sonnet: 플랜 생성·스케줄 제안·책갈피 디자인 생성 등, 구조화된 긴 출력이 필요한 처리 -
Haiku: 스팟 제안·준비물 제안·경로 정규화 등, 경량 태스크 -
gpt-image: 표지·스티커·썸네일의 이미지 생성

이러한 구분 사용을 통해, 모든 기능을 상위 모델로 구동할 때와 비교하여 API 비용을 대폭 절감했습니다. 또한 생성된 이미지는 "사용자 단위의 이미지 라이브러리"에 저장하여 재사용할 수 있도록 설계하여, 재생성 자체를 줄였습니다 (재사용은 API 호출 제로 = 원가 제로).

AI 에이전트 개발의 실제

1. 인간은 "결정"하고, 에이전트는 "만든다"

기본적인 분업은 심플합니다.

• 인간: 요구사항의 언어화, 기술 선정의 최종 판단, 리뷰, 머지(Merge)
• 에이전트: 설계 초안, 구현, 테스트 코드, 리팩터링(Refactoring), 문서화

요구사항과 유저 스토리(User Story)를 전달하면, DB 설계(Prisma 스키마)부터 API 설계까지 초안이 한꺼번에 나옵니다. 초안의 품질은 컨텍스트(Context)를 전달하는 방식에 의해 거의 결정되므로, 후술할 CLAUDE.md 운용이 효과를 발휘합니다.

2. 프론트/백엔드의 병렬 구현

Next.js 측과 NestJS 측을 별도의 에이전트가 병렬로 구현하는 스타일입니다. 먼저 인터페이스(API 사양·DTO)를 확정한 후 병렬화를 진행함으로써, 독립적인 구현에서도 정합성을 유지할 수 있었습니다. 반대로 인터페이스가 모호한 상태에서 병렬화를 하면 재작업(Retake)이 발생합니다.

3. AI가 AI를 개선하는 루프

앱 내의 AI 컨시어지(Claude API)의 프롬프트 엔지니어링(Prompt Engineering) 자체도 에이전트에게 맡겼습니다. "이 출력의 이 부분이 잘못되었다"라는 피드백을 전달하면, 프롬프트를 수정하고 회귀 확인(Regression Test)까지 수행합니다. 인간은 품질의 판정 기준을 제공하는 역할을 맡습니다.

4. 테스트·인프라도 에이전트로

• Playwright의 E2E 테스트는 25개의 spec(인증·주요 플로우·AI 기능·보안·스모크 테스트)으로 구성. CI에서 cron으로 실행하며, 실패 시 Slack으로 알림
• AWS 인프라는 Terraform으로 관리하며, 설계·구축·수정도 Claude Code가 실시
• GitHub Actions로 자동 배포 (main 머지 → 운영 환경 반영)

팀에 지식이 부족한 영역(인프라·법무)에서도 에이전트가 지식을 보완해주기 때문에, "해본 적이 없어서 못 한다"라는 말이 사라진 것이 가장 큰 수확입니다.

운용 노하우 (이것이 본론)

CLAUDE.md가 전부다

에이전트는 프롬프트마다 새로운 태스크로서 동작하기 때문에, 과거의 대화를 기억하고 있다는 전제로 지시하면 사고가 발생합니다. 사양·금지 사항·용어·아키텍처상의 결정은 CLAUDE.md에 집약하고, 결정될 때마다 문서를 업데이트하는 운용 방식을 채택했습니다.

• "왜 이 설계로 했는가"에 대한 의도까지 작성 → 에이전트의 판단이 흔들리지 않음
• 금지 사항(건드리면 안 되는 테이블, 변경하면 안 되는 API 계약)을 명시
• 용어집(도메인 용어의 정의)을 보유

태스크 분해의 입도가 품질을 결정한다

"이 기능을 만들어줘"보다는 "이 DTO를 추가 → 이 service에 메서드 추가 → 이 spec으로 테스트"와 같이, 작고 명확한 태스크로 분해할수록 아웃풋의 품질이 올라갑니다. 큰 지시는 설계 아이디어를 나누는 용도(打ち合わせ)로 사용하고, 구현은 작게 나누어 전달하는 것이 안정적입니다.

지시의 정중함은 그대로 품질로 나타난다

급할 때 내리는 짧고 무성의한 지시는 의도와 다르게 해석되기 쉽습니다. 중요한 지시일수록 배경, 제약 사항, 기대하는 결과를 구체적으로 작성해야 합니다. 이는 팀원에게 의뢰하는 것과 마찬가지였습니다.

빠지기 쉬운 함정

• 모델의 업데이트로 인해 동일한 지시라도 동작이나 품질이 변할 수 있음
• 같은 실수를 반복하는 케이스가 있음 → CLAUDE.md의 금지 사항에 추가하여 구조적으로 방지
• 보안 및 성능 리뷰는 인간의 눈이 필수적임
• 복잡한 비즈니스 로직(과금, 쿼터 관리 등)은 인간이 설계한 후 전달할 것

요약

"인간이 설계·판단하고, AI가 구현·검증한다"는 분업은 소규모 팀에게 정말 강력합니다. 반면, 컨텍스트 관리 (Context Management, CLAUDE.md)와 태스크 분해 (Task Decomposition) 설계는 인간 측의 스킬로 남습니다. 에이전트 개발의 생산성은 코드를 쓰는 속도가 아니라 지시와 문서의 질에서 결정된다는 것이 반년 동안 경험하며 느낀 실감입니다.

제작물: Yui (栞) https://shiori.life (기본 무료 · 등록 30초 · 브라우저에서 작동합니다)

회사: Sea Kids 주식회사 https://seakids.co.jp

Discussion