FY 다중 에이전트 흐름 스킬 (FY-Flow)
계약 기반 다중 지능체 협업 개발 마이크로 커널 (FY-Flow) —— AutoGen 패러다임에 맞춰 권한 초과, 작업 조각화 및 상태 교착 상태를 효과적으로 방지합니다.
통합 게이트웨이 프로토콜 (Unified Gateway Protocol)
이 스킬을 호출하는 모든 명령어는 이 게이트웨이 진입점에 집계되며, 다음과 같은 이중 분기 규칙에 따라 분류 및 판단됩니다.
1. 이중 분기 매트릭스
| 분기 유형 | 트리거 특징 및 명령어 | 처리 메커니즘 및 응답 계약 | 일반적인 시나리오 |
|---|---|---|---|
| 분기 A: 시스템 콘솔 작업 | /fy-flow help/fy-flow start/fy-flow status/fy-flow kanban/fy-flow trace | 기본 운영 엔진으로 직접 전달(0단계 사전 분류 없음), 해당 스크립트를 직접 실행하고 시스템 상태를 출력합니다. | 도움말 보기, SOP 초기화, 칸반 시작, 대시보드 검사, 오프라인 연결 도감 |
| 분기 B: 비즈니스 개발 및 상호 작용 의도 | 자연어 요구사항, 코드 수정, 기능 개발, 버그 수정, 문제 해결, /fy-flow auto | 강제 사전 실행 [분류 3문 및 단일 책임 분할] 후, 응답 첫 줄에 이중 헤더 식별자를 명시적으로 출력:`【작업 등급: L0 즉시 답변 / L1 경량 작업 / L2 표준 개발】 | 【단일 책임: 규정 준수 단일 카드 / 복합 요구사항은 N개의 원자 작업으로 분할 필요】` |
2. 비즈니스 요구사항 [분류 3문] 의사 결정 흐름
[비즈니스 요구사항 입력]
│
├─► 1. 코드/문서/설정 등 저장소 파일을 수정하게 됩니까?
│ ├─ 아니오 ──► 2. 결론을 후속 공학의 근거로 사후 추적해야 합니까?
│ │ ├─ 아니오 ───────────────► 【L0 즉시 답변】(카드 없이 직접 답변, 0밀리초 CLI 지연, 초안은 임시 보관함에 저장)
│ │ └─ 예 ───────────────► 【L1 경량 작업】(카드 생성 후 시작 대기 → 인간 승인 후 단일 역할 완료)
│ │
│ └─ 예 ──► 3. 여러 역할의 협업, 핵심 비즈니스 코드 수정 또는 공통 기본 라이브러리 변경이 필요합니까?
│ ├─ 아니오 ───────────────► 【L1 경량 작업】
│ └─ 예 ───────────────► 【L2 표준 개발 작업】(카드 생성 후 시작 대기 → 인간 승인 후 다중 역할 협업)
- 게이트웨이 등급과 CCP 탄력적 등급 매핑:
- 【L0 즉시 답변】 : 카드 없이 직접 답변, 0 상태 머신 오버헤드;
- 【L1 경량 작업】 : CCP Tier-3(Fast-Path 신속 통과, 물리적 독립 보고서 면제, 자격 증명 칸반에 직접 기록)에 매핑;
- 【L2 표준 개발】 : 규모와 계약에 따라 자동으로 CCP Tier-2(부분 최적화, 작업 시간 ≤ 4.0시간, 물리적 보고서 면제) 또는 CCP Tier-1(핵심 아키텍처 및 인터페이스 계약 강력 제약)에 매칭.
- L1/L2 비즈니스 요구사항에 속하는 경우 게이트웨이에서 단일 책임 검토를 강제 실행(작업 시간 ≤ 8.0시간, 단일 원자 인도물). 직교 영역을 넘는 요구사항은 반드시 분해하여 카드를 생성해야 합니다.
- 작업 승인 하드 레드라인: 카드 생성이 완료되면 이번 계획 세션의 최종 상태에 도달하며, 작업 카드는 반드시 [대기 중] 상태에 엄격히 머물러야 합니다. 인간 사용자가 명시적으로 작업 승인 명령(예: “시작”, “개발 시작”, “실행 확인”)을 내리기 전까지는 자동으로 [진행 중] 상태로 전환하는 것이 금지됩니다.
- 실행 상태 Task ID(예:
T0001)는 게이트웨이를 통과하여 상태 머신으로 직접 전달되며, 이중 카드 생성은 금지됩니다.
핵심 명령어 빠른 참조표 (CLI Command Quick Reference)
| 비즈니스 시나리오 | 통합 CLI 퍼사드 (cli.py) | 기본 전용 스크립트 | 핵심 기능 및 매개변수 |
|---|---|---|---|
| 작업 카드 생성 | python3 scripts/cli.py task create ... | python3 scripts/quick_task.py create ... | --name "..." --assignee "..." --stage "Sprint 2.1 메뉴 조정" --type "A" --target "..." --criteria "..." [--in-scope "file # 이유"] |
| 단계 게이트 승인/종료 | python3 scripts/check_stage_gate.py ... | python3 scripts/check_stage_gate.py ... | --action start/close --stage "Sprint 2.1 메뉴 조정"(필요에 따라 승인, 이전 종속성 자동 확인) |
| 코드화된 작업 할당 | python3 scripts/cli.py dispatch --task-id T00xx --format codex | python3 scripts/dispatch_task.py | 종속성 및 동시성 확인, [진행 중]으로 전환, Codex 하위 에이전트 도구가 직접 호출할 수 있는 JSON 매개변수 출력 |
| 작업 상태 전이 | python3 scripts/transition_task.py ... | python3 scripts/transition_task.py ... | --task-id T00xx --role DEV --from-status 진행 중 --to-status 검토 중 --token <token> --summary "핵심 변경 사항 설명" --remarks "..."(검토 요청 시 --summary 강제 포함, 차이점 및 자격 증명 스냅샷 자동 주입) |
| 인간 최종 승인 | python3 scripts/cli.py task accept ... | python3 scripts/quick_task.py accept ... | --task-id T00xx(인간 사용자 전용, 에이전트 대리 승인 금지) |
| 칸반 시작 | python3 scripts/cli.py kanban | python3 scripts/start_kanban_server.py | 기본적으로 http://127.0.0.1:32886/ 에서 시작 |
| 건강 상태 점검 | python3 scripts/cli.py status | python3 scripts/heartbeat.py | 대시보드 건강 상태, 차단 카드 및 효율성 지표 출력(하위 에이전트 인지 로밍 및 600초 초과 경고 포함) |
| 기술 스택 동기화/프로필 재계산 | - | scripts/update_agent_tech_stacks.py | --force-recalc 강제로 전문가 기술 능력 프로필 재계산 및 Subagent 내보내기 새로 고침, 기술 스택 마이그레이션 후 프로필 부실 문제 해결 |
| 연속성 검증 | python3 scripts/cli.py ccp ... | python3 scripts/cli.py ccp ... | --task-id T00xx --stage 검토 중 컨텍스트 연속성 검증 |
| 연결 전체 그림 | python3 scripts/cli.py trace | python3 scripts/generate_trace_html.py | 오프라인으로 세션 추적을 파싱, 초 단위로 전체 연결 그림 HTML 생성(0 토큰) |
| 지능형 증분 테스트 | python3 scripts/cli.py test | scripts/run_tests.py | Git 변경 사항 자동 감지, 관련 단위 테스트만 실행(초 단위), 문서 변경 시 자동 면제, --all 전체 회귀 테스트 |
8대 전문가 하위 에이전트 쓰기 권한 및 전이 간격 매트릭스
[!IMPORTANT] 물리적 격리 철칙 및 토큰 게이팅 (Dispatch Token Gating):
- 주 에이전트 (PM 엄 매니저)는 주 세션에서 스스로 개발자 역할을 가장하여 비즈니스 코드를 작성하는 것을 엄격히 금지합니다! Codex 호스트는 실제 하위 에이전트 도구를 사용하여 작업을 할당해야 합니다. 다른 호스트는 각자의 하위 에이전트 도구를 사용할 수 있습니다.
- 코드화된 할당 및 토큰 게이팅: 작업 할당 시
cli.py dispatch가 전용dispatch_token을 생성합니다. 전문 개발 역할(DEV/FRONTEND/REVIEWER/QA)은 전이 시 반드시--token <token>을携带해야 하며, 상태 머신 실행 하위에서 강력히 차단하여 스스로 역할을 가장하는 가짜 통과를 방지합니다.
Codex 데스크탑 자동 할당 계약
사용자가 명시적으로 작업 승인을 한 후, 주 에이전트는 대상 프로젝트 디렉토리에서 다음을 실행합니다.
python3 .agents/skills/fy-flow/scripts/dispatch_task.py --task-id <ID> --format codex.
표준 출력은 단일 JSON 객체이며, tool, arguments, task_id, role을 포함합니다. 진단 정보는 표준 오류로 출력됩니다.
주 에이전트는 즉시 arguments를 있는 그대로 한 번의 실제 collaboration.spawn_agent 도구 호출의 매개변수로 사용해야 합니다.
하위 에이전트가 반환될 때까지 기다린 후, 작업의 현재 상태에 따라 검토 및 테스트 전문가를 계속 할당합니다. 할당 메시지를 수동으로 재작성, 복사 또는 축약하지 마십시오.
JSON을 출력하여 할당이 완료되었다고 간주하지 말고, 주 에이전트가 직접 전문가 작업을 수행하지 마십시오. 현재 Codex 호스트에
하위 에이전트 도구가 없는 경우, 호스트 기능 부족을 명확히 보고하고 작업은 현재 상태를 유지하며, 전문가 확인을 위조하지 마십시오.
이미 할당된 전문가는 메시지의 exit_contract.required_cli만 실행해야 하며, 이중으로 카드를 생성하거나 작업을 시작하지 않아야 합니다.
사용자 승인이 이미 이번 실행을 포함하므로, 카드 생성 후 동일한 세션에서 계속 할당할 수 있습니다. 작업 승인을 받지 못한 경우에만 [대기 중] 상태에 머뭅니다.
| 하위 에이전트 식별자 | 역할 이름 | 핵심 책임 | 합법적인 상태 전이 간격 | 종료 계약 |
|---|---|---|---|---|
@flow-pm | 엄 매니저 (프로젝트 매니저) | 요구사항 분해, 등급 판단 및 카드 생성 | 대기 중 -> 진행 중 / 승인 요청 | 카드 생성 시나리오에서는 [대기 중] 상태로 멈추고 작업 승인을 기다립니다. 인간 승인 요청 |
@flow-architect | 전 아키텍트 (시스템 아키텍트) | 시스템 전체 아키텍처, 인터페이스 계약 및 기술 선택 | 대기 중 -> 진행 중 -> 완료됨 | ADR 및 아키텍처 설계 문서 생성 |
@flow-dev | 이 개발자 (개발 엔지니어) | 백엔드/풀스택 핵심 코딩 및 단위 테스트 구현 | 대기 중 -> 진행 중 -> 검토 중 | 단위 테스트 실행 필수, 개발 보고서 생성, 검토 요청 시 --summary 제공 |
@flow-frontend | 마 프론트엔드 (프론트엔드 개발 엔지니어) | Web/UI 컴포넌트 및 프론트엔드 경험 구현 | 대기 중 -> 진행 중 -> 검토 중 | 컴포넌트 렌더링 및 상호 작용 검증, 보고서 생성, 검토 요청 시 --summary 제공 |
@flow-reviewer | 주 검토자 (코드 검토 전문가) | 코드 규칙, 보안 스캔 및 품질 게이팅 | 검토 중 -> 테스트 중 / 검토 중 -> 완료됨 (Tier-3 자격 증명이 신선하고 표류하지 않은 경우 QA 우회 가능) / 검토 중 -> 반려됨 | 정적 스캔 결과 경고 없음, 검토 의견 생성 |
@flow-qa | 장 테스터 (테스트 엔지니어) | 대상 통합 테스트 및 출시 (현재 작업 관련 테스트만 실행, 전체 스크립트 금지) | 테스트 중 -> 완료됨 / 테스트 중 -> 반려됨 | 대상 테스트 케이스 작성, 실제 작업 시간 기록 |
@flow-docs | 이 문서화 (문서 엔지니어) | 인도물 문서 관리 및 사용자 매뉴얼 | 대기 중 -> 진행 중 -> 완료됨 | GB/T 7713 학술 및 공학 규범 준수 |
@flow-devops | 여 개특 (운영 관리자) | 브랜치 병합, 릴리스 빌드 및 Git 기록 보호 | 대기 중 -> 진행 중 -> 완료됨 | 파이프라인 통과 확인, PR 차단 해결 |
모듈형 규약 엔터티 인덱스 (필요 시 특정 규범 파일 참조)
특정 비즈니스 시나리오에 진입하는 경우에만 에이전트는 view_file을 호출하여 해당 규약의 엔터티 Markdown 파일을 참조해야 합니다.
- 초기 로드 / 콜드 스타트 SOP:
references/02-bootstrap/01-initialization_sop.md참조 - 작업 생성 / 단일 책임 판단:
references/01-gateway/01-task_classification.md참조 - 작업 상태 전이 / 게이팅 규칙 / 역할 권한:
references/03-engine/01-state_flow_rules.md참조 - 컨텍스트 인계 / 에이전트 간 핸드오프 (CCP):
references/04-ccp/01-ccp_protocol_spec.md참조 - 칸반 서비스 운영 / PR 자동 차단 해제:
references/05-kanban/01-kanban_operations.md참조 - Git 브랜치 병합 / 감사 로그 및 측정:
references/06-governance/01-git_and_audit_spec.md참조
[!NOTE] IP 차단 목록 보호 (IP Blocking List Protection):
.agents/skills/fy-flow/references/07-security/01-ip_blocking_list.md파일은 IP 거부 목록 정책을 정의합니다. AI 비정상 행위(예: 빈번한 잘못된 작업 생성, 위조된 보고서 등)가 감지되면 즉시 해당 에이전트의 IP를 차단 목록에 추가하고 모든 권한을 취소합니다. Git 사전 커밋 훅 (Git Pre-commit Hook):.agents/skills/fy-flow/references/08-git-hooks/01-pre-commit_hook_setup.md파일은 Git 사전 커밋 훅 설치 및 구성을 정의합니다. 통과하지 못한 커밋은 강제로 차단되어 저장소 보안과 코드 품질을 보장합니다.