FlexGodX/자율 에이전트 개발 사이클

자율 에이전트 개발 사이클 (품질 게이트 파이프라인)

이 스킬은 Quest Nova (Flutter + Go + PostgreSQL 16 + Drift/SQLite)의 자율 생성을 통해 개발 및 검증된 5단계 엔지니어링 워크플로우와 다중 에이전트 중재 파이프라인을 공식화합니다.

이는 단계 간 사람의 개입 없이 높은 아키텍처 충실도, 제로 데이터 손실, 엄격한 보안(제로 트러스트/IDOR), 그리고 수학적으로 검증된 분산 동기화를 보장합니다.

[!NOTE] 역공학 제외: 역공학 단계는 생략/비활성화됩니다. 파이프라인은 목표 정의 및 기능 명세 작성(또는 기존 제품 개요를 입력으로 사용)으로 직접 시작됩니다.

---

1. 핵심 아키텍처 원칙

1. 제로 중단 자율성: 오케스트레이터는 모든 단계를 자율적으로 진행합니다. 확인은 사용자에게 묻는 것이 아니라 엄격한 품질 게이트 감사에서 비롯됩니다.
2. 클린 컨텍스트 독립 검증: 리뷰어와 심사자는 클린 컨텍스트를 가진 전용 하위 에이전트로 생성됩니다(이전 채팅 추론 없이 검증 가능한 대상 결과물, 참조 명세, 명시적 평가 기준만 수신).
3. 만장일치 승인 장벽: 모든 감사자/심사자가 명시적인 APPROVED 판정을 내릴 때까지 다음 단계로의 전환이 차단됩니다. 결함 목록(CHANGES_REQUESTED)은 즉각적인 수정-재감사 루프를 트리거합니다.
4. 폴백 모델 라우팅: 기본 추론 모델이 속도 제한(예: HTTP 429 할당량 소진)을 경험하면 파이프라인은 에이전트 역할과 클린 컨텍스트 경계를 엄격히 유지하면서 사용 가능한 고처리량 모델(예: Gemini 3.8 Flash)로 작업을 원활하게 라우팅합니다.

---

2. 5단계 파이프라인

flowchart TD
    P1["Phase 1: 목표 수립 및 기능 명세"] --> QG1{"품질 게이트 1: 명세 감사"}
    QG1 -->|"CHANGES_REQUESTED"| P1Fix["명세 결함 해결"]
    P1Fix --> QG1
    QG1 -->|"APPROVED (만장일치)"| P2["Phase 2: 시스템 설계 및 아키텍처"]
    P2 --> QG2{"품질 게이트 2: 3명의 에이전트 법정"}
    QG2 -->|"CHANGES_REQUESTED"| P2Fix["아키텍처 개선"]
    P2Fix --> QG2
    QG2 -->|"APPROVED (만장일치)"| P3["Phase 3: QA 산출물 및 구현 계획"]
    P3 --> QG3{"품질 게이트 3: 추적 가능성 교차 검토"}
    QG3 -->|"CHANGES_REQUESTED"| P3Fix["계획 및 QA 정렬"]
    P3Fix --> QG3
    QG3 -->|"APPROVED (만장일치)"| P4["Phase 4: 구현 (백엔드 + 클라이언트)"]
    P4 --> P5["Phase 5: 전체 검증, 스트레스 테스트 및 릴리스"]

---

3. 산출물 명명 규칙

파이프라인에서 생성되는 모든 산출물은 버전이 지정된 파일입니다. 기존 산출물을 그 자리에 덮어쓰지 말고 다음 버전을 만드세요.

<ARTIFACT-NAME>-<date>-<NN>.md

• <ARTIFACT-NAME> — 산출물의 UPPER_SNAKE 이름: GOAL, SPECIFICATION, DESIGN, QA_ARTIFACT, IMPLEMENTATION_PLAN, RELEASE_NOTES.
• <date> — ISO 형식의 생성 날짜 YYYY-MM-DD.
• <NN> — 같은 이름의 산출물이 하루 안에 여러 개 생성될 때 이를 구분하는 두 자리 시퀀스 번호(01, 02, …). 특정 날짜의 첫 번째 산출물에서는 01로 시작하고, 같은 날 해당 산출물의 후속 개정이 있을 때마다 증가시킵니다. 카운터는 산출물 이름별로 관리되므로, 같은 날 생성된 다른 산출물은 같은 번호를 가질 수 있습니다(예: GOAL-2026-11-10-01.md와 DESIGN-2026-11-10-01.md). 새 날짜가 시작되면 카운터는 다시 01부터 시작됩니다.

예시:

산출물	그날의 첫 번째 산출물	그날의 두 번째 산출물
Goal	docs/GOAL-2026-11-10-01.md	docs/GOAL-2026-11-10-02.md
Specification	docs/SPECIFICATION-2026-11-10-01.md	docs/SPECIFICATION-2026-11-10-02.md
Design	docs/DESIGN-2026-11-10-01.md	docs/DESIGN-2026-11-10-02.md

규칙:

1. 단계 결과물 및 모든 상호 참조(품질 게이트 프롬프트, 계획, 릴리스 노트)는 정확한 버전 파일명을 인용해야 하며, docs/GOAL.md와 같은 버전 없는 이름을 사용해서는 안 됩니다.
2. 산출물 이름에 대한 가장 높은 <NN>이 현재 공식 버전입니다. 이전 버전은 감사 추적으로 그대로 유지됩니다.
3. 품질 게이트는 전달된 특정 버전을 감사하고 해당 파일명을 판정에 기록합니다.

이 스킬 전체에서 <date>와 <NN>은 위에서 설명된 날짜와 시퀀스 번호를 나타냅니다.

---

4. 단계별 실행 가이드

Phase 1: 목표 수립 및 기능 명세 (품질 게이트 1)

• 목표: 요구사항/개요를 기반으로 명시적인 시스템 경계, 사용자 루프, 도메인 모델 및 기술 명세를 공식화합니다.
• 결과물:
  • docs/GOAL-<date>-<NN>.md: 전역 시스템 범위, 핵심 불변 조건, 완료 정의(DoD).
  • docs/SPECIFICATION-<date>-<NN>.md: 엔티티 스키마, 시간 메커니즘, 동기화 프로토콜, OCC 버전 관리, 3-way 병합 규칙, IDOR 보호, DDL 스키마.
• 품질 게이트 1 (클린 컨텍스트 감사자):
  • 하위 에이전트 생성 (typeName: "research").
  • 오직 docs/SPECIFICATION-<date>-<NN>.md와 기준(완전성, 보안, 데이터 무결성, 일관성)만 제공합니다.
  • APPROVED가 반환될 때까지 루프합니다.

Phase 2: 시스템 설계 및 "3명의 에이전트 법정" (품질 게이트 2)

• 목표: 확장 가능하고 내결함성이 있는 백엔드와 반응형 클라이언트를 설계합니다.
• 결과물: docs/DESIGN-<date>-<NN>.md (시스템 설계 문서: 백엔드, 클라이언트, 보안).
• 품질 게이트 2 (3명의 에이전트 법정): 클린 컨텍스트를 가진 3개의 독립적인 하위 에이전트를 생성합니다:
  1. 심사자 1 (백엔드 및 시스템 아키텍트): DB 스키마, 트랜잭션 경계, 행 수준 잠금, 위상 정렬 DAG, 파티션 구성, OCC를 평가합니다.
  2. 심사자 2 (클라이언트 및 UI 아키텍트): 오프라인 우선 DB(Drift/SQLite), 백그라운드 격리, 프레임 예산(< 16.6 ms), 뮤테이션 큐 병합, BLoC 상태 머신을 평가합니다.
  3. 심사자 3 (보안 및 엣지 케이스 비평가): 경쟁 조건, 콜드 스타트 교착 상태, 에코 루프, 토큰 재생(RTR), 세션 도용, IDOR 취약점을 식별합니다.
  • 세 심사자 모두가 APPROVED를 반환해야 진행할 수 있습니다.

Phase 3: QA 산출물, 추적 가능성 계획 및 품질 게이트 3

• 목표: 코드를 작성하기 전에 명세, 아키텍처, 테스트 간의 100% 양방향 추적 가능성을 보장합니다.
• 결과물:
  • docs/QA_ARTIFACT-<date>-<NN>.md: 전체 승인 기준(AC-XX), 단위, 통합, 분산 동기화(TC-SYNC-XX), 스트레스 테스트 시나리오(STRESS-XX).
  • docs/IMPLEMENTATION_PLAN-<date>-<NN>.md: QA 케이스에 직접 매핑된 단계별 작업 분류.
• 품질 게이트 3 (교차 감사자):
  • docs/QA_ARTIFACT-<date>-<NN>.md의 모든 단일 승인 기준 및 엣지 케이스가 docs/IMPLEMENTATION_PLAN-<date>-<NN>.md의 구현 단계에 직접 매핑되는지 확인합니다.
  • APPROVED가 반환될 때까지 루프합니다.

Phase 4: 구현 및 테스트 검증

1. 데이터베이스 마이그레이션: 복합 인덱스와 파티셔닝을 사용하여 모든 DDL 마이그레이션을 적용합니다.
2. 백엔드 엔진:
   • 클린 아키텍처: domain/, repository/, usecase/, delivery/http/.
   • 단위 및 통합 테스트 실행: cd backend && go test -v ./....
3. 클라이언트 엔진:
   • 핵심 시간 유틸리티(PlainDate, FloatingTime, SparseSortOrder).
   • 3-Way 차등 병합 엔진(5개 체크리스트 시나리오, 데이터 손실 없음 참고).
   • 제자리 뮤테이션 병합 및 진행 중 경쟁 처리(MutationQueueManager).
   • BLoC 아키텍처 및 적응형 UI(데스크톱 3-팬 + 모바일 네비게이션).
   • 클라이언트 테스트 실행: cd client && flutter test.
   • 린터 검증: cd client && flutter analyze (0개 이슈).

Phase 5: 스트레스 테스트, 릴리스 및 인계

1. 분산 동기화 검증: 다중 장치 동시성, OCC 충돌, 에코 억제, HTTP 410 부트스트랩 조정을 실행합니다.
2. 스트레스 테스트:
   • 데이터베이스 연결 풀 포화(STRESS-01): 풀 누수 0개를 가진 동시 워커.
   • UI 프레임 예산 벤치마크(STRESS-02): 1000개 작업을 < 16.6 ms 내에 처리 (안정적인 60/120 FPS).
3. 산출물 컴파일:
   • 네이티브 백엔드 바이너리 빌드: go build -o bin/<service> cmd/<service>/main.go.
   • 클라이언트 번들 빌드: flutter build bundle / flutter build macos / flutter build web.
4. 릴리스 노트: 검증된 메트릭, DoD 체크리스트, 실행 지침을 문서화한 docs/RELEASE_NOTES-<date>-<NN>.md를 생성합니다.

---

5. 감사자 및 심사자 프롬프트 템플릿

품질 게이트 1, 2, 3에 대해 클린 컨텍스트 하위 에이전트를 호출할 때 사용하는 프롬프트 템플릿은 references/auditor_prompts.md를 참조하세요.