# 파이프라인 단계 명세 (Pipeline Stages Specification) **문서 작성일**: 2026-03-02 **역할**: 미미르 (UX/UI & Documentation Designer) **참조**: anu-guide.md Section 1.6 - 6단계 자동 파이프라인 --- ## 개요 (Overview) Anu 자동화 파이프라인은 사용자의 지시부터 AI 수정 완료까지 6개의 구조화된 단계를 거쳐 작동합니다. 각 단계는 명확한 입출력, 활성화 조건, 그리고 실패 처리 방식을 가집니다. ``` 지시 전달 → AI 작업 수행 → 파일 기록 → 오류 검사 → 리마인더 → AI 빠른 수정 ``` --- ## Stage 1: 지시 전달 (Instruction Delivery) ### 정의 사용자의 지시와 관련 매뉴얼 문서를 수집하여 시스템에 전달하는 단계 ### 입력 (Input) - 사용자의 자연어 지시 (UserPrompt) - 선택적 파라미터 및 옵션 - 참조 문서 (anu-guide.md 등) - 프로젝트 컨텍스트 (현재 상태, 요구사항) ### 출력 (Output) - 정규화된 지시 객체 (Normalized Instruction Object) - `instruction_id`: UUID 형식의 고유 ID - `timestamp`: ISO 8601 형식의 작성 시간 - `user_input`: 원본 지시 텍스트 - `context_documents`: 참조 문서 목록 - `execution_plan`: 단계별 실행 계획 (선택적) - Stage 2로 전송할 준비된 데이터 ### 트리거 조건 (Trigger) - 사용자가 프롬프트 제출 (UserPromptSubmit hook 발동) - 지시가 비어있지 않음 - 선택적 문서 검증 통과 ### 실패 시 동작 (Failure Handling) - **검증 실패**: 사용자에게 오류 메시지 반환 및 재입력 요청 - **문서 누락**: 기본 템플릿 제공 또는 단계 스킵 - **시스템 오류**: 오류 로그 기록 및 사용자 알림 ### 현재 구현 상태 ✅ **구현됨** - `UserPromptSubmit` hook이 이 단계를 처리 --- ## Stage 2: AI 작업 수행 (AI Task Execution) ### 정의 AI 에이전트가 지시를 해석하고 코드 변경, 문서 작성 등의 작업을 수행하는 단계 ### 입력 (Input) - Stage 1에서 생성된 정규화된 지시 객체 - 프로젝트 파일 시스템 (읽기 가능) - 환경 설정 및 도구 (Bash, File Read/Write 등) - 선택적 AI 프롬프트 템플릿 ### 출력 (Output) - 수행된 작업 결과 (Work Artifacts) - 생성된/수정된 파일 목록 - 실행된 명령어 로그 - 생성된 코드 또는 문서 - 작업 메타데이터 - `stage_2_id`: 단계별 고유 ID - `execution_time`: 실행 소요 시간 - `status`: `completed` | `partial` | `error` - `changes_summary`: 변경 사항 요약 ### 트리거 조건 (Trigger) - Stage 1이 `completed` 상태 - 정규화된 지시 객체 수신 - AI 에이전트 팀 시스템 준비 완료 ### 실패 시 동작 (Failure Handling) - **부분 완료**: 완료된 작업은 Stage 3으로 진행, 미완료 항목 로깅 - **타임아웃**: 작업 중단 및 현재까지의 결과 저장 - **리소스 부족**: 재시도 큐에 추가 또는 사용자 알림 - **문법/로직 오류**: 오류 세부사항 기록 후 Stage 4로 진행 ### 현재 구현 상태 ✅ **구현됨** - 팀 에이전트 시스템 (Team Agent System) 운영 중 --- ## Stage 3: 파일 자동 기록 (Audit Trail Recording) ### 정의 Stage 2의 모든 작업을 감시 추적하여 불변 감시 로그에 기록하는 단계 ### 입력 (Input) - Stage 2의 작업 결과 및 메타데이터 - 파일 변경 이벤트 (PostToolUse hook) - 실행된 도구 호출 기록 - 타임스탬프 및 세션 정보 ### 출력 (Output) - 감시 로그 파일 (audit-trail.jsonl) - 각 라인: JSON 형식의 단일 작업 기록 - 필드: `timestamp`, `action_type`, `tool_used`, `input`, `output`, `status` - 감시 리포트 (선택적) - 작업 시간선 (Timeline) - 변경된 파일 목록 - 도구 사용 통계 ### 트리거 조건 (Trigger) - Stage 2 실행 시작 (사전 기록) - 각 도구 사용 후 (PostToolUse hook) - Stage 2 완료 시 (사후 기록) ### 실패 시 동작 (Failure Handling) - **로그 쓰기 실패**: 메모리 버퍼에 임시 저장 후 재시도 - **디스크 용량 부족**: 경고 알림 및 오래된 로그 아카이빙 - **권한 문제**: 오류 기록 및 관리자 알림 - **기록 불완전**: 부분 기록이라도 저장 후 Stage 4 진행 ### 현재 구현 상태 ✅ **구현됨** - PostToolUse hook이 audit-trail.jsonl에 기록 --- ## Stage 4: 오류 자동 검사 (Automated Quality Control) ### 정의 Stage 2와 3의 결과를 검증하여 오류를 발견하고 품질을 보증하는 단계 ### 입력 (Input) - Stage 2의 작업 결과 (생성/수정된 파일) - Stage 3의 감시 로그 (audit-trail.jsonl) - 프로젝트 규칙 및 체크리스트 - 문법 검사 규칙 (Linting rules) - 코드 스타일 가이드 - 보안 체크리스트 - 문서 완성도 기준 ### 출력 (Output) - 품질 검사 리포트 (QC Report) - `qc_id`: 검사 고유 ID - `severity_levels`: critical | warning | info - `issues`: 발견된 문제 목록 - `issue_id` - `file_path` - `line_number` - `description` - `suggested_fix` (선택적) - `pass_rate`: 통과율 (%) - `timestamp`: 검사 완료 시간 ### 트리거 조건 (Trigger) - Stage 3이 `completed` 상태 - 감시 로그 수신 완료 - 최소 1개 이상의 파일 변경 감지 ### 실패 시 동작 (Failure Handling) - **검사 도구 오류**: 사용 가능한 대체 검사 방식 적용 - **False Positive**: 제외 규칙 적용 및 리포트에 표시 - **치명적 오류 (Critical)**: Stage 5로 진행하면서 상위 경고 플래그 - **경고 수준 (Warning)**: 계속 진행하되 검토 표시 - **정보 수준 (Info)**: 기록만 남기고 진행 ### 현재 구현 상태 🔄 **구현 중** - Phase 2, 1팀 작업 진행 중 --- ## Stage 5: 프로젝트 리마인더 (Project Reminder & Review) ### 정의 사용자와 팀에게 작업 완료를 알리고 검토 기회를 제공하는 단계 ### 입력 (Input) - Stage 2의 작업 결과 요약 - Stage 4의 품질 검사 리포트 - 프로젝트 메타데이터 (담당자, 우선순위 등) - 선택적 리뷰 템플릿 ### 출력 (Output) - 리마인더 메시지/알림 - 완료된 작업 요약 - 변경 사항 하이라이트 - 발견된 이슈 (있을 경우) - 리뷰 체크리스트 - [ ] 작업 결과 확인 - [ ] 변경 사항 검토 - [ ] 품질 검사 리포트 검토 - [ ] 추가 수정 필요 여부 결정 - 다음 단계 선택지 제공 - Stage 6 진행 (AI 빠른 수정) - 수동 검토 대기 - Stage 2 재실행 ### 트리거 조건 (Trigger) - Stage 4가 `completed` 상태 - 품질 검사 리포트 생성 완료 - 사용자 알림 설정 활성화 ### 실패 시 동작 (Failure Handling) - **알림 전송 실패**: 로컬 알림 기록 및 다음 접속 시 표시 - **메타데이터 누락**: 기본값 사용하여 계속 진행 - **리뷰 대기 초과**: 자동으로 Stage 6 진행 (선택적) - **사용자 거절**: 작업 결과 저장 및 아카이빙 ### 현재 구현 상태 ⏳ **예정** - Phase 3 예정 --- ## Stage 6: AI 빠른 수정 (AI Quick Fix & Finalization) ### 정의 발견된 오류를 자동으로 수정하거나 사용자 피드백을 반영하여 최종화하는 단계 ### 입력 (Input) - Stage 4의 품질 검사 리포트 (이슈 목록) - Stage 5의 사용자 피드백 (선택적) - 원본 작업 결과 (Stage 2의 결과물) - 수정 규칙 및 템플릿 ### 출력 (Output) - 수정된 파일들 - 자동 수정이 적용된 결과 - 변경 사항 마킹 (어디가 수정되었는지) - 최종 완료 리포트 - `execution_id`: 전체 파이프라인 고유 ID - `total_duration`: 전체 소요 시간 - `stages_completed`: 완료된 단계 목록 - `issues_resolved`: 해결된 이슈 수 - `status`: `success` | `partial_success` | `failed` - 아카이브 (모든 로그, 리포트 포함) ### 트리거 조건 (Trigger) - Stage 5가 `completed` 상태 - 사용자가 명시적으로 Stage 6 진행 승인 - 또는 자동 진행 정책 활성화 (QC Pass 시) ### 실패 시 동작 (Failure Handling) - **자동 수정 실패**: 해당 이슈는 수동 수정 대기로 표시 - **부분 수정**: 성공한 수정 사항은 적용, 실패 항목은 기록 - **파일 충돌**: 충돌 상세 정보 기록 및 사용자 알림 - **최종 검증 실패**: 완료 보류 및 Stage 4로 되돌리기 ### 현재 구현 상태 ⏳ **예정** - Phase 3 예정 --- ## 파이프라인 상태 코드 (Pipeline Status Codes) 각 단계는 다음 4가지 상태 중 하나를 가집니다: | 상태 | 코드 | 설명 | |------|------|------| | 대기 중 | `pending` | 단계 활성화 조건 충족 전 대기 상태 | | 실행 중 | `running` | 단계 작업 진행 중 | | 완료 | `completed` | 단계 작업 성공적으로 완료 | | 실패 | `failed` | 단계 작업 중 복구 불가능한 오류 발생 | ### 상태 조회 예시 ``` Stage 1: completed Stage 2: completed Stage 3: completed Stage 4: running Stage 5: pending Stage 6: pending ``` --- ## 전이 조건 (Transition Rules) 다음 조건들이 만족될 때만 한 단계에서 다음 단계로 전이합니다: ### Stage 1 → Stage 2 - `Stage 1 status = completed` - 지시 객체 유효성 검증 통과 - **실패 시**: Stage 1에서 재시작 ### Stage 2 → Stage 3 - `Stage 2 status = completed` 또는 `partial` - 최소 1개 이상의 작업 결과 생성 - **실패 시**: 작업 결과 롤백 및 Stage 2 재실행 ### Stage 3 → Stage 4 - `Stage 3 status = completed` - 감시 로그 쓰기 성공 확인 - **실패 시**: 로그 복구 시도 후 Stage 4 진행 또는 대기 ### Stage 4 → Stage 5 - `Stage 4 status = completed` - 품질 검사 리포트 생성 완료 - **자동 조건**: Critical 이슈 0개 (선택적) - **실패 시**: 검사 재실행 또는 Stage 2로 되돌리기 ### Stage 5 → Stage 6 - `Stage 5 status = completed` - 사용자 명시적 승인 또는 자동 진행 정책 활성화 - 선택적: 일정 시간 경과 (예: 24시간 대기) - **실패 시**: Stage 5에 유지 또는 프로젝트 보류 ### 파이프라인 완료 - `Stage 6 status = completed` - 최종 리포트 생성 및 저장 - 모든 아카이브 파일 저장 완료 - **완료 후**: 사용자에게 최종 알림 전송 --- ## 재실행 정책 (Retry Policy) 각 단계의 실패 시 재실행 전략: | 단계 | 재시도 횟수 | 대기 시간 | 우선순위 | |------|-----------|---------|---------| | Stage 1 | 즉시 | - | 사용자 입력 | | Stage 2 | 최대 2회 | 지수 백오프 (1초, 5초) | 자동 | | Stage 3 | 최대 3회 | 지수 백오프 (1초, 5초, 15초) | 자동 | | Stage 4 | 최대 1회 | 즉시 | 자동 | | Stage 5 | 최대 1회 | 즉시 | 자동 | | Stage 6 | 최대 2회 | 지수 백오프 (5초, 30초) | 자동 | --- ## 동시성 (Concurrency) - **단계 간 동시성**: 제한 없음 (순차 처리) - **단계 내 도구 동시성**: 최대 3개 병렬 실행 가능 - **파이프라인 간 격리**: 각 파이프라인은 독립적으로 실행 - **리소스 관리**: 시스템 리소스 모니터링 및 자동 조절 --- ## 성능 목표 (Performance SLO) | 메트릭 | 목표 | 비고 | |--------|------|------| | Stage 1 처리 시간 | < 1초 | 사용자 입력 즉시 처리 | | Stage 2 실행 시간 | 상황 의존 | 작업 복잡도에 따라 달라짐 | | Stage 3 기록 시간 | < 100ms | 감시 로그 쓰기 | | Stage 4 검사 시간 | < 5초 | 파일 크기에 따라 달라질 수 있음 | | Stage 5 알림 시간 | < 2초 | 리마인더 생성 및 전송 | | Stage 6 수정 시간 | 상황 의존 | 이슈 수와 복잡도에 따라 달라짐 | | **전체 파이프라인** | **< 5분** | 일반적인 작업 기준 | --- ## 에러 코드 참조 (Error Code Reference) ### Stage별 에러 코드 ``` ERR_S1_VALIDATION: Stage 1 검증 실패 ERR_S1_EMPTY_INPUT: 빈 지시 입력 ERR_S1_MISSING_CONTEXT: 필수 컨텍스트 누락 ERR_S2_EXECUTION: Stage 2 실행 실패 ERR_S2_TIMEOUT: Stage 2 타임아웃 ERR_S2_TOOLING: Stage 2 도구 오류 ERR_S3_LOGGING: Stage 3 로깅 실패 ERR_S3_DISK_FULL: Stage 3 디스크 용량 부족 ERR_S4_QC: Stage 4 품질 검사 실패 ERR_S4_CRITICAL: Stage 4 치명적 오류 발견 ERR_S5_NOTIFICATION: Stage 5 알림 실패 ERR_S5_METADATA: Stage 5 메타데이터 누락 ERR_S6_FIX: Stage 6 자동 수정 실패 ERR_S6_CONFLICT: Stage 6 파일 충돌 ``` --- ## 통합 흐름도 (Integration Flow) ``` ┌─────────────────┐ │ Stage 1 │ 지시 전달 │ 입력 수신 및 │ │ 정규화 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Stage 2 │ AI 작업 수행 │ AI 에이전트 │ │ 작업 실행 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Stage 3 │ 감시 로깅 │ 작업 기록 및 │ │ 감시 추적 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Stage 4 │ 품질 검사 │ 자동 QC 검사 │ │ 이슈 발견 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Stage 5 │ 리마인더 │ 사용자 알림 │ │ 검토 기회 제공 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Stage 6 │ 빠른 수정 │ 자동 수정 또는 │ │ 최종화 │ └────────┬────────┘ │ ▼ ┌────────┐ │ 완료 │ └────────┘ ``` --- ## 체크리스트 (Implementation Checklist) ### 현재 구현 상태 (2026-03-02 기준) - [x] **Stage 1**: 완전 구현 (UserPromptSubmit hook) - [x] 지시 입력 수집 - [x] 문서 참조 로드 - [x] 정규화 처리 - [x] **Stage 2**: 완전 구현 (Team Agent System) - [x] 에이전트 작업 실행 - [x] 결과 수집 - [x] 메타데이터 생성 - [x] **Stage 3**: 완전 구현 (PostToolUse hook) - [x] audit-trail.jsonl 기록 - [x] 타임스탬프 관리 - [x] 로그 회전 정책 - [ ] **Stage 4**: 구현 중 (Phase 2) - [ ] QC 규칙 정의 - [ ] 검사 도구 통합 - [ ] 리포트 생성 - [ ] **Stage 5**: 예정 (Phase 3) - [ ] 알림 시스템 구축 - [ ] 리뷰 인터페이스 설계 - [ ] 메타데이터 관리 - [ ] **Stage 6**: 예정 (Phase 3) - [ ] 자동 수정 엔진 - [ ] 충돌 해결 로직 - [ ] 최종 아카이브 --- ## 문서 관리 (Document History) | 버전 | 작성일 | 변경사항 | |------|--------|---------| | 1.0 | 2026-03-02 | 초안 작성 - 6단계 명세 완성 | **다음 검토 예정**: Phase 4 (Stage 4 구현 완료 후) --- **작성자**: 미미르 (UX/UI & Documentation Designer) **최종 수정**: 2026-03-02 **라이선스**: Internal Use Only