SPEC 기반 개발

MoAI-ADK의 SPEC 기반 개발 방법론을 자세히 안내합니다. SPEC은 에이전틱 하네스의 입력이자 토크노믹스의 숨은 도구입니다 — 요구사항이 파일로 남아 있으면 세션을 끊고 /clear로 컨텍스트를 비워도 SPEC 한 줄로 작업을 이어갈 수 있습니다. 같은 설명을 되풀이하며 토큰을 태울 일이 없습니다. 왜냐하면 맥락이 세션에 머무는 게 아니라 파일에 남기 때문에, 어제 한 결정이 오늘 커밋으로 직행하고, harness 안의 모든 에이전트 가 같은 SPEC 을 읽고 같은 방향으로 일합니다.

정보

한 줄 요약: SPEC은 “AI와 나눈 대화를 문서로 남기는 것"입니다. 세션이 끊겨도 SPEC만 있으면 언제든 이어서 작업할 수 있습니다.

정보

SPEC은 Agent를 위한 것입니다: SPEC은 개발자가 외워야 하는 문서가 아닙니다. Agent가 작업할 때 들여다보는 문서입니다. 원리와 쓰임새만 개념적으로 알고 있으면 충분합니다.

정보

SPEC은 3개 파일로 구성됩니다: /moai plan 실행 시 spec.md (GEARS 요구사항), plan.md (구현 계획), acceptance.md (인수 기준) 3개 파일이 동시에 생성됩니다.

SPEC (Specification) 은 프로젝트의 요구사항을 구조화된 형식으로 정의한 문서입니다.

일상적인 비유로 설명하면, SPEC은 요리 레시피와 같습니다. 요리할 때 머릿속으로만 기억하면 재료를 빠뜨리거나 순서를 잊기 쉽습니다. 하지만 레시피를 적어두면 누구든 같은 요리를 정확하게 만들 수 있습니다.

AI와 대화하며 코드를 짤 때 가장 큰 걸림돌은 맥락 유실입니다.

flowchart TD
    A["AI와 1시간 동안 대화\n인증 방식, DB 스키마, API 설계 논의"] --> B["좋은 결론 도출\nJWT + Redis 세션 관리로 결정"]
    B --> C["세션 끊김\n토큰 한도 초과, 다음 날 작업 재개 등"]
    C --> D["맥락 유실\n어제 논의한 내용을 AI가 기억 못함"]
    D --> E["처음부터 다시 설명\nJWT를 쓸지, 세션을 쓸지 다시 논의"]
    E --> A

맥락 유실이 발생하는 구체적인 상황:

SPEC은 대화 내용을 파일로 저장해 이 문제를 뿌리부터 해결합니다. 파일에 남은 결정은 컨텍스트 윈도우와 상관없이 그대로 살아남습니다 — 하네스 엔지니어링에서 말하는 “durable state in files” (파일에 담긴 지속 상태) 의 대표적인 예입니다.

flowchart TD
    A["AI와 대화\n기능 요구사항 논의"] --> B["좋은 결론 도출"]
    B --> C["SPEC 문서 자동 생성\n.moai/specs/SPEC-AUTH-001/spec.md"]
    C --> D["세션 끊김"]
    D --> E["SPEC 읽고 작업 재개\n/moai run SPEC-AUTH-001"]
    E --> F["이어서 구현 진행\n이전 결정사항 모두 보존"]

SPEC 유무에 따른 차이:

정보

SPEC 없이 작업하는 경우:

어제 “사용자 인증 기능"을 두고 1시간 동안 AI와 이야기를 나눴다고 해봅시다. JWT를 쓸지 세션을 쓸지, 토큰 만료 시간은 얼마로 할지, 리프레시 토큰은 어디에 저장할지… 이걸 처음부터 다시 이야기해야 합니다.

SPEC이 있는 경우:

아래 한 줄이면 어제 결정한 내용 그대로 구현을 시작합니다.

bash 복사

> /moai run SPEC-AUTH-001

GEARS (Generalized Approach to Requirements Syntax) 는 v3.0.0부터 MoAI-ADK의 공식 요구사항 표기법입니다. 자연어의 모호함을 제거하고, 테스트로 검증할 수 있는 형식으로 요구사항을 기술합니다. 신규 SPEC은 모두 GEARS 표기를 사용합니다.

레거시 호환 — EARS (만료 2026-11-22): GEARS 이전의 EARS (Easy Approach to Requirements Syntax) 표기는 6개월간(2026-11-22 만료) 하위 호환성을 유지합니다. 기존 SPEC 워크플로우 규칙 일부가 여전히 EARS 표기를 참조할 수 있으나, 신규 SPEC은 GEARS를 사용합니다. 아래 5가지 패턴은 EARS와 GEARS가 공유하는 요구사항 유형이며, 예시는 레거시 EARS 표기를 기준으로 합니다.

시스템이 항상 준수해야 하는 요구사항입니다. 별도 조건 없이 늘 적용됩니다.

형식: “시스템은 ~해야 한다”

예시:

- id: REQ-001
  type: ubiquitous
  priority: HIGH
  text: "시스템은 모든 사용자 입력을 검증해야 한다"
  acceptance_criteria:
    - "모든 입력값에 대해 타입 검증 수행"
    - "SQL Injection 방지를 위한 파라미터화된 쿼리 사용"
    - "XSS 방지를 위한 출력 이스케이프"

일상 비유: “운전할 때는 항상 안전벨트를 착용해야 한다"와 같습니다. 특별한 조건 없이 항상 지켜야 합니다.

특정 이벤트가 발생했을 때 시스템이 어떻게 반응해야 하는지 정의합니다.

형식: “WHEN ~하면, IF ~라면, THEN ~해야 한다”

flowchart TD
    A["WHEN\n이벤트 발생"] --> B{"IF\n조건 확인"}
    B -->|조건 충족| C["THEN\n기대 동작"]
    B -->|조건 불충족| D["ELSE\n대안 동작"]

예시:

- id: REQ-002
  type: event-driven
  priority: HIGH
  text: |
    WHEN 사용자가 로그인 버튼을 클릭하면,
    IF 이메일과 비밀번호가 유효하면,
    THEN JWT 토큰을 발급하고 대시보드로 리다이렉트해야 한다
  acceptance_criteria:
    - given: "등록된 사용자 계정이 있고"
      when: "올바른 이메일과 비밀번호로 로그인하면"
      then: "200 응답과 함께 JWT 토큰 발급"
      and: "토큰 만료 시간은 1시간"

일상 비유: “초인종이 울리면 (WHEN), 모니터로 확인해서 아는 사람이면 (IF), 문을 열어준다 (THEN)“와 같습니다.

특정 상태가 유지되는 동안 시스템이 어떻게 동작해야 하는지 정의합니다.

형식: “WHILE ~인 동안, ~해야 한다”

예시:

- id: REQ-003
  type: state-driven
  priority: MEDIUM
  text: |
    WHILE 사용자가 로그인된 상태인 동안,
    시스템은 세션을 5분마다 갱신해야 한다
  acceptance_criteria:
    - "마지막 활동으로부터 5분 경과 시 자동 갱신"
    - "세션 만료 5분 전 알림 표시"
    - "30분 무활동 시 자동 로그아웃"

일상 비유: “에어컨이 켜져 있는 동안 (WHILE), 실내 온도를 25도로 유지해야 한다"와 같습니다.

시스템이 절대 해서는 안 되는 것을 정의합니다. 주로 보안 관련 요구사항에 사용합니다.

형식: “시스템은 ~하면 안 된다”

예시:

- id: REQ-004
  type: unwanted
  priority: CRITICAL
  text: "시스템은 비밀번호를 평문으로 저장하면 안 된다"
  acceptance_criteria:
    - "비밀번호는 bcrypt로 해싱 (cost factor 12)"
    - "해싱되지 않은 비밀번호가 로그에 포함되지 않음"
    - "데이터베이스에 평문 비밀번호 저장 불가"

- id: REQ-005
  type: unwanted
  priority: CRITICAL
  text: "시스템은 하드코딩된 비밀키를 사용하면 안 된다"
  acceptance_criteria:
    - "모든 비밀키는 환경 변수 또는 비밀 관리자 사용"
    - "코드에 비밀키 포함되지 않음"
    - "Git 커밋에 비밀키 포함 방지"

일상 비유: “열쇠를 현관 매트 아래에 두면 안 된다"와 같습니다. 하지 말아야 할 것을 명시합니다.

구현이 권장되지만 필수는 아닌 기능입니다.

형식: “가능하다면, ~해야 한다”

예시:

- id: REQ-006
  type: optional
  priority: LOW
  text: "가능하다면, 시스템은 로그인 시 이메일 알림을 발송해야 한다"
  acceptance_criteria:
    - "이메일 서버가 구성된 경우에만 동작"
    - "알림 비활성화 옵션 제공"

일상 비유: “시간이 되면 디저트도 만들면 좋겠다"와 같습니다. 있으면 좋지만 없어도 괜찮습니다.

SPEC 문서는 manager-spec 에이전트가 자동으로 만듭니다. 개발자가 GEARS 형식을 외울 필요는 없습니다. 자연어로 요청하면 에이전트가 알아서 옮겨 씁니다.

/moai plan 실행 시 하나의 SPEC 디렉토리 안에 3개 파일이 동시에 생성됩니다:

정보

위 3개 파일 외에, plan 단계는 세션 간 진행 상태를 추적하는 progress.md도 함께 생성합니다 (라이프사이클 단계별 audit-ready 신호 기록). 규모가 큰 Tier L SPEC의 경우 설계·조사 산출물인 design.md와 research.md가 추가로 작성됩니다.

---
id: SPEC-AUTH-001               # 고유 식별자
title: 사용자 인증 시스템         # 명확하고 간결한 제목
priority: HIGH                  # HIGH, MEDIUM, LOW
status: draft                   # draft, in-progress, implemented, completed
created: 2025-01-12             # 생성일
updated: 2025-01-12             # 최종 수정일
author: 개발팀                   # 작성자
version: 1.0.0                  # 문서 버전
---

# 사용자 인증 시스템

## 개요
JWT 기반 사용자 인증 시스템 구현

## 요구사항
### Ubiquitous
- 시스템은 모든 API 요청에 인증을 요구해야 한다

### Event-driven
- WHEN 사용자가 로그인하면, THEN JWT를 발급해야 한다

### Unwanted
- 시스템은 비밀번호를 평문으로 저장하면 안 된다

## 제약 조건
- API 응답 시간 500ms 이내
- 비밀번호 bcrypt 해싱 (cost factor 12)

## 의존성
- Redis (세션 관리)
- PostgreSQL (사용자 데이터)

# 구현 계획

## 작업 분해
1. 사용자 모델 및 마이그레이션 생성
2. JWT 토큰 발급/검증 유틸리티 구현
3. 로그인/회원가입 API 엔드포인트 구현
4. 인증 미들웨어 구현
5. Refresh Token 갱신 로직 구현

## 기술 스택
- Go 1.23 + Fiber v2
- PostgreSQL 16 + GORM
- Redis 7 (세션/토큰 저장)

## 위험 분석
| 위험 | 영향 | 완화 전략 |
| --- | --- | --- |
| 토큰 탈취 | HIGH | Refresh Token 회전, HttpOnly 쿠키 |
| 무차별 대입 | MEDIUM | Rate Limiting, 계정 잠금 |

# 인수 기준

## 시나리오

### AC-01: 정상 로그인
- **Given** 등록된 사용자 계정이 있고
- **When** 올바른 이메일과 비밀번호로 로그인하면
- **Then** 200 응답과 JWT 토큰 세트 반환

### AC-02: 잘못된 자격증명
- **Given** 등록된 사용자 계정이 있고
- **When** 잘못된 비밀번호로 로그인하면
- **Then** 401 응답과 일반적인 오류 메시지 반환

## 엣지 케이스
- 만료된 Refresh Token으로 갱신 시 401 응답
- 동시 로그인 제한 초과 시 가장 오래된 세션 만료

## 품질 게이트
- API 응답 시간: 500ms 이내 (P95)
- 테스트 커버리지: 85% 이상

SPEC 생성은 /moai plan 명령어 하나로 시작됩니다.

flowchart TD
    A["사용자 요청\n자연어로 기능 설명"] --> B["manager-spec 에이전트 실행"]
    B --> C["요구사항 분석\n모호한 부분 질문"]
    C --> D["GEARS 형식 변환\n5가지 유형으로 분류"]
    D --> E["인수 기준 작성\nGiven-When-Then 형식"]
    E --> F["SPEC 3개 파일 생성\nspec.md + plan.md + acceptance.md"]
    F --> G["검토 요청\n사용자에게 확인"]

실행 방법:

# SPEC 생성 명령어
> /moai plan "사용자 인증 기능 구현"

이 명령어를 실행하면 다음이 자동으로 진행됩니다:

1. 요구사항 분석: manager-spec이 “사용자 인증 기능"이 무엇을 의미하는지 분석합니다
2. 명확화 질문: 모호한 부분이 있으면 사용자에게 질문합니다 (예: “JWT와 세션 중 어떤 방식을 선호하시나요?”)
3. GEARS 변환: 자연어를 5가지 요구사항 유형으로 자동 분류합니다
4. 3개 파일 생성: .moai/specs/SPEC-AUTH-001/ 디렉토리에 spec.md, plan.md, acceptance.md 3개 파일을 동시에 생성합니다
5. 검토 요청: 생성된 SPEC을 사용자에게 보여주고 확인을 요청합니다

주의

중요: 에이전트가 생성한 SPEC 문서는 반드시 한 번 검토하세요. AI가 요구사항을 잘못 해석하거나 누락할 수 있습니다. 특히 인수 기준이 테스트 가능한지, 우선순위가 적절한지 확인하는 것이 좋습니다.

.moai/
└── specs/
    ├── SPEC-AUTH-001/
    │   ├── spec.md          # GEARS 요구사항
    │   ├── plan.md          # 구현 계획
    │   └── acceptance.md    # 인수 기준
    ├── SPEC-PAYMENT-001/
    │   ├── spec.md
    │   ├── plan.md
    │   └── acceptance.md
    └── SPEC-SEARCH-001/
        ├── spec.md
        ├── plan.md
        └── acceptance.md

각 SPEC은 라이프사이클을 따라 상태가 바뀝니다.

flowchart TD
    Start(( )) -->|"/moai plan 실행"| draft["draft\n작성 중"]
    draft -->|"/moai run 실행"| in_progress["in-progress\n구현 중"]
    in_progress -->|"구현 완료"| implemented["implemented\n구현 완료"]
    implemented -->|"/moai sync 실행"| completed["completed\n완료"]
    draft -->|"요구사항 거부"| rejected["rejected\n거부"]

실제로 /moai plan을 실행하여 생성된 SPEC의 예시입니다.

# SPEC 생성
> /moai plan "JWT 기반 사용자 인증 시스템. 로그인, 회원가입, 토큰 갱신 기능 포함"

아래와 같이 .moai/specs/SPEC-AUTH-001/ 디렉토리에 3개 파일이 생성됩니다.

spec.md – GEARS 요구사항:

---
id: SPEC-AUTH-001
title: JWT 기반 사용자 인증 시스템
priority: HIGH
status: draft
created: 2025-01-15
version: 1.0.0
---

# JWT 기반 사용자 인증 시스템

## 개요
JWT 토큰을 사용한 사용자 인증 시스템.
로그인, 회원가입, 토큰 갱신 기능을 구현한다.

## 요구사항

### Ubiquitous
- REQ-U01: 시스템은 모든 인증 토큰을 HTTPS로만 전송해야 한다
- REQ-U02: 시스템은 모든 사용자 입력을 검증해야 한다

### Event-driven
- REQ-E01: WHEN 사용자가 회원가입 폼을 제출하면,
  IF 이메일이 중복되지 않으면,
  THEN 계정을 생성하고 환영 이메일을 발송해야 한다
- REQ-E02: WHEN 사용자가 로그인하면,
  IF 자격증명이 유효하면,
  THEN Access Token (1시간)과 Refresh Token (7일)을 발급해야 한다

### Unwanted
- REQ-N01: 시스템은 비밀번호를 평문으로 저장하면 안 된다
- REQ-N02: 시스템은 만료된 Refresh Token으로 새 토큰을 발급하면 안 된다

### Optional
- REQ-O01: 가능하다면, 소셜 로그인 (Google, GitHub)을 지원해야 한다

## 제약 조건
- 비밀번호: bcrypt (cost factor 12)
- Access Token 만료: 1시간
- Refresh Token 만료: 7일
- API 응답 시간: 500ms 이내 (P95)

plan.md – 구현 계획:

# 구현 계획

## 작업 분해
1. 사용자 모델 및 DB 마이그레이션 생성
2. 비밀번호 해싱 유틸리티 구현
3. JWT 토큰 발급/검증 유틸리티 구현
4. 회원가입 API 엔드포인트 구현
5. 로그인 API 엔드포인트 구현
6. 인증 미들웨어 구현
7. Refresh Token 갱신 로직 구현

## 기술 스택
- Go 1.23 + Fiber v2
- PostgreSQL 16 + GORM
- Redis 7 (Refresh Token 저장)

## 위험 분석
| 위험 | 영향 | 완화 전략 |
| --- | --- | --- |
| 토큰 탈취 | HIGH | Refresh Token 회전, HttpOnly 쿠키 |
| 무차별 대입 | MEDIUM | Rate Limiting, 계정 잠금 |

acceptance.md – 인수 기준:

# 인수 기준

## 시나리오

### AC-01: 정상 로그인
- **Given** 등록된 사용자 계정이 있고
- **When** 올바른 이메일과 비밀번호로 로그인하면
- **Then** 200 응답과 JWT 토큰 세트 (Access + Refresh) 반환

### AC-02: 잘못된 비밀번호
- **Given** 등록된 사용자 계정이 있고
- **When** 잘못된 비밀번호로 로그인하면
- **Then** 401 응답

### AC-03: 중복 회원가입
- **Given** 이미 등록된 이메일이 있고
- **When** 같은 이메일로 회원가입하면
- **Then** 409 응답

### AC-04: 토큰 갱신
- **Given** 유효한 Refresh Token이 있고
- **When** 토큰 갱신을 요청하면
- **Then** 새로운 Access Token 반환

## 품질 게이트
- API 응답 시간: 500ms 이내 (P95)
- 테스트 커버리지: 85% 이상

이 SPEC으로 구현 시작하기:

# SPEC 확인 후 구현 시작
> /moai run SPEC-AUTH-001

이 명령어 하나로 설정된 개발 방법론 (DDD 또는 TDD) 에 따라 SPEC의 모든 요구사항을 자동으로 구현합니다. 신규 프로젝트는 TDD (RED-GREEN-REFACTOR), 기존 프로젝트는 DDD (ANALYZE-PRESERVE-IMPROVE) 사이클을 사용합니다.

일상적인 요청을 GEARS 형식으로 어떻게 바꾸는지 비교합니다.

정보

GEARS 형식을 직접 작성하지 않아도 됩니다. /moai plan에 자연어로 요청하면 manager-spec 에이전트가 자동으로 GEARS 형식으로 변환합니다. 위 표는 어떻게 변환되는지 이해하기 위한 참고 자료입니다.

SPEC은 한 번 쓰고 끝나는 문서가 아니라 계획(plan) → 구현(run) → 동기화(sync) 라는 라이프사이클을 따릅니다. MoAI-ADK는 각 SPEC이 어느 시대(era)의 규약으로 작성됐는지 자동으로 분류하고, 현대 규약을 따르는 SPEC에만 드리프트(drift, 규약 이탈) 검사를 겁니다.

모든 V3R6 SPEC은 3단계로 완결됩니다. 과거에 존재하던 4번째 단계(Mx-phase)는 폐지되었습니다 — MX 태그 검증은 별도 단계가 아니라 sync 단계에서 처리되는 횡단 관심사(cross-cutting concern)입니다.

sync 단계가 끝나면 그 커밋의 SHA가 progress.md의 §E.4 Sync-phase Audit-Ready Signal 섹션에 sync_commit_sha 필드로 기록됩니다. 이 필드의 존재 여부가 SPEC이 현대 규약(V3R6)을 완전히 따랐는지 판별하는 핵심 신호입니다.

정보

Mx-phase 폐지: 이전 버전에는 plan/run/sync 다음에 Mx-phase라는 4번째 단계와 mx_commit_sha 필드가 있었습니다. 현재는 폐지되어 3단계로 통합되었습니다. MX 코드 주석(@MX 태그) 관리는 sync 단계 안에서 함께 수행됩니다.

모든 SPEC은 작성된 시기의 규약에 따라 정확히 하나의 era 버킷으로 분류됩니다.

era 분류는 spec.md 프론트매터의 created: 날짜와 progress.md의 섹션 구조를 자동으로 검사해 결정됩니다. 경계가 모호한 경우 프론트매터에 era: V3R6 같은 명시적 필드를 추가해 직접 지정할 수 있습니다.

V2.x · V3R2-R4 · V3R5 로 분류된 SPEC은 grandfather 절이 보호합니다. 이 세 era는 작성 당시의 규약을 제대로 지킨 것이므로 현대 V3R6 규약을 거슬러 적용하지 않습니다.

• grandfather SPEC은 감사 결과에서 era_final: true 로 표시됩니다.
• 섹션 누락, 커밋 SHA 부재 등 어떤 패턴이든 드리프트 결함이 보고되지 않습니다.
• 과거 SPEC을 현대 규약에 맞춰 일괄 정규화하는 것은 운영상 불가능하고 실익이 없기 때문입니다.

라이프사이클 드리프트 검사(moai spec audit)는 오직 V3R6 SPEC에만 적용됩니다.

• 현대 era 경계 기준일은 2026-04-01 입니다. 이 날짜 이후 작성되고 V3R6 신호를 갖춘 SPEC만 드리프트 검사 대상입니다.
• 내부적으로 IsModern() 판정은 V3R6일 때만 참(true) 을 반환합니다.
• 즉, grandfather era(V2.x/V3R2-R4/V3R5)는 드리프트 검사에서 항상 제외되며 결함으로 분류되지 않습니다.

이 분류 체계 덕분에 오래된 SPEC에서 거짓 양성(false positive)이 튀어나오지 않고, 지금 작성 중인 SPEC의 규약 준수만 정확하게 검증할 수 있습니다.

• SPEC 라이프사이클 – 이 문서가 다루는 SPEC 문서의 라이프사이클(관문 포함)을 단계별로 따라갑니다
• MoAI-ADK란? – MoAI-ADK의 전체 구조를 이해합니다
• 개발 방법론 (DDD/TDD) – SPEC을 기반으로 안전하게 코드를 구현하는 DDD/TDD 방법론을 배웁니다
• TRUST 5 품질 – 구현된 코드의 품질을 검증하는 기준을 배웁니다