v4.0 적응형 워크플로 정책: Harness CLI는 알맞은 개발 절차를 어떻게 고를까¶
Quick Answer: Harness CLI v4.0은 먼저 작업을 분류한 뒤 필요한 절차만 선택합니다. 질문과 읽기 전용 확인은
noop또는direct, 작고 분명한 로컬 변경은guarded, 여러 단계이거나 위험하고 위임 또는 재개가 필요한 목표는planned입니다. 계획 상태는 별도로none,reuse,create로 관리하므로 짧은 확인을 새 계획으로 잘못 만들지 않습니다.
모든 요청에 같은 의식을 적용하면 AI 코딩 도구는 금방 무거워집니다. 한 줄짜리 조회에는 작업 항목이 필요하지 않지만 문서, 테스트, 릴리스 근거가 포함된 변경은 기억만으로 처리해서는 안 됩니다. v4.0은 이 경계를 명확하게 만듭니다.
네 가지 워크플로 라우트¶
| 라우트 | 사용할 때 | 일반적인 결과 |
|---|---|---|
noop |
빈 입력, 확인, 실행할 요청이 없을 때 | 저장소를 변경하지 않음 |
direct |
질문, 읽기 전용 조사, 상태 확인 | 근거가 있는 답변 |
guarded |
작고 분명한 로컬 변경 | 편집 게이트와 집중 검증 |
planned |
여러 단계, 불명확함, 위험, 위임, 재개 가능한 목표 | 영속 작업 항목과 playbook |
라우트는 적응형입니다. 요청이 길다고 항상 planned인 것도 아니고, 파일을 바꾼다고 팀을 만들어야 하는 것도 아닙니다. 범위와 위험으로 결정합니다.
계획 영속화는 별도의 결정¶
실질적인 요청에서는 두 가지를 따로 판단합니다.
- 어떤 라우트로 실행할 것인가?
- 계획 상태를 어떻게 처리할 것인가?
계획 상태는 다음과 같습니다.
none: 영속 계획을 만들거나 재사용하지 않음.reuse: 사용자가 명시적으로continue또는resume한 경우 조건에 맞는 활성 계획을 재사용함.create: 새로운 planned 목표를 위한 작업 항목을 생성함.
이 구조는 “알겠어”, “계속해” 같은 짧은 답변을 새 목표로 오해하는 문제를 줄입니다. 같은 세션의 확인은 현재 작업 항목에 붙이고, 클라이언트를 넘는 재개는 명시적인 신호와 필요한 handoff만 불러옵니다.
planned 라우트에는 무엇이 추가되나?¶
계획형 실행은 다음의 경계를 남깁니다.
- 목표와 범위를 분류하고 기록합니다.
- brainstorming, plan, TDD, systematic debugging 등 필요한 playbook만 선택합니다.
- 파일을 수정하기 전에
pre-edit-safety-gate를 통과합니다. - 완료를 주장하기 전에 검증 근거를 저장합니다.
planned가 항상 팀을 뜻하지는 않습니다. 중단 후 재개해야 하는 목표는 solo harness로 실행할 수 있고, 독립적인 영역만 팀으로 나눕니다. 의존성이 있는 변경은 순서대로 처리합니다.
Dry run과 live readiness는 다르다¶
dry-run은 설정, 라우트, 입력이 타당한지 확인하지만 외부 모델 공급자, 브라우저 세션, MCP 서버, 로그인 계정이 실제로 준비됐다는 뜻은 아닙니다. 상태 화면에서는 설정 수락, 로컬 검사, 외부 의존성, 사람의 승인을 구분해야 합니다. 운영에도 좋고 검색·답변 엔진이 정확히 인용하기에도 좋습니다.
권장 시작 순서¶
새 checkout에서는 먼저 다음 명령을 실행합니다.
aios init --all
aios doctor --native --verbose
현재 라우트 표는워크플로 정책에서 확인할 수 있습니다. 클라이언트 설정은빠른 시작, 중단 후 재개하는 실행은Solo Harness를 참고하세요.
FAQ¶
모든 코드 변경에 계획이 필요한가요?¶
아닙니다. 작고 명확한 변경은 guarded로 충분합니다. 여러 의존 단계, 설계 불확실성, 위험, 위임, 재개 필요성이 있을 때 planned를 사용합니다.
planned는 팀 전용인가요?¶
아닙니다. planned는 분류이며 단일 클라이언트, solo harness, 팀 중 어디서든 실행할 수 있습니다.
종료 상태의 계획을 재개할 수 있나요?¶
할 수 없습니다. 완료 또는 blocked 상태의 계획은 활성 계획처럼 암묵적으로 계속되지 않습니다. 새 목표를 만들거나 조건에 맞는 비종료 작업을 명시적으로 재개해야 합니다.
구현 경계는 어디서 확인하나요?¶
아키텍처 문서에서 CLI, ContextDB, 클라이언트 투영, 런타임 상태의 관계를 설명합니다. 문제 해결에는 라우트와 검증 실패에 대한 다음 단계가 정리되어 있습니다.
작은 일에는 적은 절차를, 신뢰성이 필요한 일에는 추적 가능한 근거를. 이것이 v4.0의 핵심입니다.