AI 에이전트 워크플로는 어떻게 고를까? Harness CLI 판단 가이드¶
Quick Answer: 질문과 읽기 전용 조사는
direct, 작고 명확한 변경은guarded, 여러 단계·불확실성·위험·위임·재개가 필요한 작업은planned를 사용합니다. 실행 가능한 요청이 없으면noop입니다. 라우트는 사용하는 클라이언트의 브랜드가 아니라 작업의 성격으로 결정됩니다.
AI 에이전트 팀은 첫 판단에서 자주 실패합니다. 모든 요청에 무거운 절차를 적용하면 느려지고, 조정이 필요한 일을 아무 계획 없이 진행하면 재현성이 떨어집니다. 터미널을 열기 전에 사용할 수 있는 판단법을 정리했습니다.
가장 작은 질문부터 시작하기¶
다음 순서로 확인합니다.
- 실행 가능한 요청이 있는가? 없으면
noop입니다. - 읽기와 설명만 필요한가? 그렇다면
direct입니다. - 하나의 작고 명확한 변경이며 검증도 분명한가? 그렇다면
guarded입니다. - 설계, 여러 의존 단계, 위험, 위임, 복구가 필요한가? 그렇다면
planned입니다.
이 순서를 먼저 보여 주면 첫 화면이 이해하기 쉽고, 답변 엔진도 “어떤 라우트를 왜 선택하는가”를 정확히 인용할 수 있습니다.
판단표¶
| 질문 | 예 | 아니요 |
|---|---|---|
| 구체적인 작업이 있는가? | 다음 분류로 이동 | noop |
| 조사나 설명만 필요한가? | direct |
다음 분류로 이동 |
| 작고 명확한 하나의 편집인가? | guarded |
다음 분류로 이동 |
| 설계, 순서, 위임, 복구가 필요한가? | planned |
안전한 guarded인지 재확인 |
예시 1: “최신 릴리스에서 무엇이 바뀌었나요?”¶
읽기 전용 질문입니다. changelog와 관련 문서, 저장소 이력을 확인하고 링크와 근거를 포함해 답하면 됩니다. 계획은 필요하지 않습니다.
예시 2: “README의 오타 하나를 고치고 docs check를 실행해 주세요.”¶
범위가 작고 검증도 분명합니다. guarded로 편집 게이트를 통과하고, README를 수정하고, 집중 검사를 실행한 뒤 결과를 보고합니다.
예시 3: “문서, 블로그, 홈페이지에 새 정책을 네 언어로 반영해 주세요.”¶
콘텐츠 설계, 번역, 내비게이션, 메타데이터, 검증이 연결됩니다. 한 사람이 해도 planned가 알맞습니다.
라우트 다음에 playbook 고르기¶
라우트는 다음 과정의 종류를 정하는 분류입니다.
- 방향이 불명확함: brainstorming;
- 승인된 여러 단계 요구사항: writing a plan;
- 동작 변경 또는 버그 수정: test-driven development;
- 관찰된 실패: systematic debugging;
- 완료를 주장하기 직전: verification before completion。
파일을 만들거나 삭제하거나 동작을 바꾸기 전에는 어떤 라우트에서도 pre-edit-safety-gate가 필요합니다. guarded라고 해서 최종 검증을 생략하지도 않습니다.
실행면 선택하기¶
라우트가 정해지면 작업을 끝낼 수 있는 가장 작은 실행면을 선택합니다.
- 강하게 결합된 변경은 하나의 클라이언트에서 처리합니다.
- 중단 후 돌아와야 하는 목표는 solo harness를 사용합니다.
- 독립적인 영역과 분리된 쓰기 범위가 있을 때만 팀으로 나눕니다.
Codex CLI, Claude Code, Gemini CLI, OpenCode, Grok Build 등은 같은 프로젝트 계약을 공유할 수 있습니다. 클라이언트는 인터페이스를 바꾸지만 라우트의 의미를 몰래 바꾸어서는 안 됩니다.
편집뿐 아니라 라우트도 검증하기¶
인수인계에는 다음을 포함합니다.
- 선택한 라우트와 이유;
- 변경한 파일과 공개 표면;
- 실행한 검사와 결과;
- 확인하지 못한 외부 의존성;
- 작업이 종료되지 않았다면 다음 행동.
새 checkout에서는 다음을 실행합니다.
aios init --all
aios doctor --native --verbose
그 다음워크플로 정책, 빠른 시작, 긴 작업이라면Solo Harness를 확인하세요.
FAQ¶
문서 작업에 planned는 너무 무겁지 않나요?¶
여러 언어, 내비게이션, 메타데이터, 테스트, 빌드까지 걸친다면 조정과 복구를 위해 적절합니다.
planned면 항상 병렬 에이전트를 사용하나요?¶
아닙니다. 독립적인 영역만 병렬화하고, 공유 내비게이션이나 같은 생성물은 순서대로 통합합니다.
라우트를 잘못 골랐다면요?¶
빨리 다시 분류하세요. 새 의존성이 발견되면 guarded에서 planned로 올리고, 탐색으로 불확실성이 사라지면 planned를 간소화할 수 있습니다.
시스템 경계는 어디서 확인하나요?¶
아키텍처, Agent Team 운영, 문제 해결을 읽어 보세요.