feat(agent): Architect 컨테이너 + sub-agent 루프 (메인/검증/컨펌)

[hagyutae]

배경

A 의 본체. P 가 정리한 이슈 받아 OO 설계 결과물 생성 → 사용자 컨펌까지. 본 이슈의 spec 은 docs/architect-design-spec.md (M4 첫 이슈) 를 따른다.

스코프

agents/architect/ 컨테이너

• 다른 에이전트와 동일 토폴로지: FastAPI + LangGraph + AgentCard + A2A server
• assistant_id = "architect"
• L 의 graph 도구 + Doc Store MCP 클라이언트 (PRD/Epic/Story 조회용)

LangGraph 그래프 — sub-agent 루프

proposal §3.2 의 패턴 그대로:

flowchart LR
    Input([P 위임 입력]) --> Main[메인 설계 노드<br/>LLM A — 코딩/설계 특화]
    Main --> Verify[검증 노드<br/>LLM B — 추론 특화<br/>요구사항 / OO 원칙 검증]
    Verify -->|반려| Main
    Verify -->|통과| Confirm[최종 컨펌 노드<br/>LLM C — 균형형]
    Confirm -->|재작업| Main
    Confirm -->|승인| User[사용자 컨펌 대기<br/>state=INPUT_REQUIRED]
    User -->|컨펌| Persist[L: atlas_upsert_design<br/>+ Doc Store 저장]
    User -->|수정| Main
    Persist --> Out([END])

Loading

• 3개 LLM 모델 분리 가능 (Role Config 의 llm.sub_agents.*)
• M4 진입 시 Role Config 의 sub_agents 스키마 정의 + 기본값 (모두 같은 모델)

기술 스택 결정 자료

• LLM 자체 지식 + 코드베이스 의존성 파일 (pyproject.toml 등) 읽기
• 코드베이스 정밀 분석은 M5+ (사용자 답변 Q9 인지)

사용자 컨펌 후 처리

• L 의 atlas_upsert_design(...) 호출 → graph db 에 status: designed 노드/엣지 생성
• L 의 upsert_* 로 설계 결과물 (md + mermaid) 자체도 Doc Store 저장

도중 사용자 의견 구하기

• A 가 sub-agent 루프 도중 "결정 필요" 판단 시 → state=INPUT_REQUIRED 로 SendStreamingMessage 보냄
• UG 가 라우팅 (M4 별 이슈) 통해 사용자 도달

비-스코프

• Eng / QA 와의 협력 (M5+)
• Diff 색인 후 status: implemented 전이 (M5+)
• A 내부의 다자간 논의 / 유관 Eng 소집 (M5+)

검증

• A 컨테이너 정상 부팅
• sub-agent 루프 단위 테스트 (각 단계 LLM mock)
• guestbook 시나리오 — P 의 이슈 받아 설계 결과물 생성 (별 E2E 이슈)
• 사용자 컨펌 후 graph db 에 status: designed 노드 생성 확인