Architect

개요

Architect는 코드를 분석하고, 버그의 근본 원인을 진단하며, 실행 가능한 아키텍처 권고를 제공하는 에이전트입니다. 모든 주장은 구체적인 file:line 근거를 기반으로 합니다.

읽기 전용(read-only) 에이전트로, 코드를 직접 수정하지 않습니다. 코드를 읽지 않고 판단하는 것은 추측이며, 모호한 권고("리팩토링을 고려해보세요")는 하지 않습니다.

언제 쓰는가

• 복잡한 버그의 근본 원인을 분석할 때
• 아키텍처 결정에 대한 트레이드오프를 평가할 때
• 구현 검증이 필요할 때
• ralplan 합의 검토에서 기술적 반론을 제공할 때

사용 예시

"이 레이스 컨디션의 원인을 분석해줘"
"이 모듈 구조의 트레이드오프를 평가해줘"
"이 구현이 설계 의도대로 되어 있는지 검증해줘"

분석 프로세스

1. 컨텍스트 수집 (필수): Glob으로 프로젝트 구조 매핑, Grep/Read로 관련 구현 찾기, 의존성/테스트 확인 (병렬 실행)
2. 가설 수립: 코드를 읽기 전에 가설을 먼저 문서화합니다
3. 교차 검증: 가설을 실제 코드와 대조, 모든 주장에 file:line 근거를 제시합니다
4. 결과 정리: 요약, 진단, 근본 원인, 우선순위별 권고, 트레이드오프, 참조

비명확한 버그의 경우 4단계 프로토콜을 따릅니다. 근본 원인 분석 → 패턴 분석 → 가설 검증 → 권고 도출. 3번의 수정 시도가 실패하면 아키텍처 자체에 의문을 제기합니다.

ralplan 합의 검토

ralplan 합의 검토에서 Architect는 추가 역할을 맡습니다.

• Antithesis: 선호되는 방향에 대한 가장 강한 반론을 제시합니다
• Tradeoff tension: 무시할 수 없는 트레이드오프를 지적합니다
• Synthesis: 경쟁 옵션의 장점을 보존하는 합성안을 제시합니다 (가능한 경우)
• deliberate 모드에서는 원칙 위반 플래그를 명시적으로 표시합니다

다른 에이전트와의 조합

• debugger: 빌드 에러 같은 구체적인 에러 수정은 debugger 몫입니다
• critic: 계획 검토가 필요하면 critic에 위임합니다
• qa-tester: 런타임 검증이 필요하면 qa-tester와 협력합니다 (진단 → 검증 루프)
• executor: 분석 결과를 바탕으로 구현은 executor에 넘깁니다

Architect + QA-Tester 진단-검증 루프

CLI 앱이나 서비스 디버깅에 쓸 만한 워크플로우입니다.

1. Architect가 이슈를 진단하고 근본 원인 분석을 제공합니다
2. Architect가 구체적인 명령과 예상 출력이 포함된 테스트 계획을 출력합니다
3. QA-Tester가 tmux에서 테스트 계획을 실행하고 실제 출력을 캡처합니다
4. 검증 실패 시 결과를 Architect에 피드백하여 재진단합니다
5. 검증 성공까지 반복합니다

레퍼런스