MoAI-ADK 5분 시작 — SPEC-First DDD

MoAI-ADK는 "명세를 먼저 쓰고, 그 명세를 따라 구현한다"는 SPEC-First 원칙 위에 세워진 개발 방법론이자 도구 모음이다. 코드를 바로 짜기 전에 무엇을 만들지 분명히 적어 두면, 구현이 흔들리지 않고 검증 기준도 명확해진다. 이 문서는 MoAI-ADK를 처음 접하는 사람이 핵심 흐름인 plan-run-sync를 5분 안에 머릿속에 그릴 수 있도록 돕는다.

SPEC을 먼저 쓰는 이유

코드를 먼저 짜면, 만드는 사람조차 "정확히 무엇을 완성한 것인지" 나중에 흐려지기 쉽다. SPEC을 먼저 쓰면 요구사항·완료 조건·범위가 문서로 고정되어, 구현은 그 문서를 만족시키는 작업으로 단순해진다. 또한 명세가 있으면 "이게 끝난 게 맞나"라는 판단을 주관이 아니라 합의된 기준으로 내릴 수 있다.

plan-run-sync 세 단계

MoAI-ADK의 작업은 크게 세 단계의 순환으로 이뤄진다. 각 단계는 역할이 분명히 나뉜다.

• plan: 요구사항을 명세로 정리한다. 무엇을, 어떤 조건에서, 어떻게 검증할지 적는다.
• run: 명세를 따라 구현한다. 테스트로 동작을 보증하며 코드를 채워 간다.
• sync: 변경 사항을 문서와 이력에 반영한다. 다음 작업이 깔끔한 상태에서 출발하도록 정리한다.

이 세 단계가 한 바퀴 돌면 하나의 SPEC이 명세에서 구현, 그리고 정리된 기록까지 완결된다.

DDD와 TDD — 검증을 앞세우는 방식

구현 단계에서 MoAI-ADK는 검증을 앞세운다. 새 기능은 테스트를 먼저 쓰고 구현으로 채우는 TDD 방식이, 기존 코드를 다듬을 때는 현재 동작을 먼저 테스트로 고정하는 DDD 방식이 어울린다. 어느 쪽이든 "동작을 먼저 보증하고 코드를 손댄다"는 원칙은 같다.

다음 단계

MoAI-ADK의 본질은 "명세 → 구현 → 정리"라는 단순한 순환이다. 이 순환이 몸에 배면, 무엇을 만드는지 늘 분명한 상태로 개발을 이어 갈 수 있다. 우선은 아주 작은 기능 하나를 골라 SPEC을 한 문단으로 적어 보고, 그 문단을 만족시키는 구현이 무엇일지 떠올려 보는 것부터 시작하길 권한다.