날것의 CLI 명령에서 신뢰할 수 있는 AI 에이전트 워크플로로¶
Quick Answer: 신뢰성은 명령 시퀀스 주변에 명시적인 경계를 둘 때 생깁니다. 요청을 분류하고, 가장 작은 라우트를 고르고, 편집을 보호하고, 복구 가치가 있는 작업만 저장하고, 검증 근거로 결과를 확인합니다. Harness CLI는 이 경계를 제공하지만 모든 읽기 전용 질문을 무거운 계획으로 만들지는 않습니다.
Shell alias는 AI 코딩 클라이언트를 시작할 수 있습니다. 하지만 작업이 안전한지, 이전 시도를 재개해야 하는지, 성공한 명령이 실제 변경 범위를 모두 확인했는지는 설명하지 못합니다. 날것의 CLI 래퍼와 신뢰할 수 있는 워크플로의 차이는 실행을 둘러싼 계약입니다.
중요한 다섯 가지 경계¶
1. 입력 경계¶
요청을 명시적인 목표로 바꾸고 질문, 조사, 작은 편집, 여러 단계 목표를 분리합니다. 빈 입력이나 확인만으로 작업을 만들지 않습니다.
2. 라우팅 경계¶
클라이언트나 playbook을 고르기 전에 noop, direct, guarded, planned를 선택합니다. 프로세스를 위험에 맞추기 위해서입니다.
3. 편집 경계¶
파일을 만들거나 바꾸기 전에 영향 범위, 의존성, 스타일, 테스트 커버리지를 확인하는 pre-edit-safety-gate를 실행합니다. 코드 그래프를 사용할 수 없으면 대상 검색과 기존 테스트를 명시적인 대체 근거로 사용합니다.
4. 상태 경계¶
계속할 가치가 있을 때만 계획을 저장합니다. 프로젝트 registry는 사용 가능한 컨텍스트를 설명하지만 모든 prompt에 전체 이력을 자동으로 주입한다는 뜻은 아닙니다. 재개할 때는 선택한 작업과 handoff만 불러옵니다.
5. 근거 경계¶
변경 표면에 맞는 검사를 실행하고 각 검사가 무엇을 증명하는지 보고합니다. 빌드 성공은 빌드를 증명할 뿐 외부 브라우저 세션, 모델 provider, 사람의 승인을 자동으로 증명하지 않습니다.
구체적인 마이그레이션 패턴¶
이전 절차가 다음과 같다고 가정해 봅시다.
claude "update the docs"
git diff
이 방식은 답하지 않은 질문을 너무 많이 남깁니다. 다음 계약으로 바꿉니다.
- 대상 공개 표면과 언어를 명시합니다.
- 콘텐츠, 내비게이션, 테스트를 모두 다루면
planned로 분류합니다. - 파일 소유권과 수용 검사를 포함한 계획을 씁니다.
- 각 편집 묶음 전에
pre-edit-safety-gate를 실행합니다. - 생성 디렉터리를 소스 변경에 포함하지 않습니다.
- 콘텐츠 계약, 사이트 동기화, strict build를 실행합니다.
- 정확한 검증 결과와 확인하지 못한 외부 의존성을 기록합니다.
구체적인 명령은 프로젝트마다 달라도 순서는 재사용할 수 있습니다. 그래서 Codex CLI, Claude Code, Gemini CLI, OpenCode, Grok Build 등으로 옮기기 쉽습니다.
브라우저 작업도 명시적으로 만들기¶
브라우저 자동화에서도 상태를 숨기지 않는 것이 중요합니다.
- 대상 profile로 보이는 CDP 브라우저를 실행합니다.
- 연결합니다.
- semantic snapshot이나 텍스트를 읽습니다.
- 보이는 동작 하나를 수행합니다.
- 상태 변화를 기다린 뒤 페이지를 다시 읽습니다.
- 인증 화면과 민감한 외부 전송은 사람이 관리합니다.
이렇게 하면 브라우저 과정을 감사할 수 있고, 설정된 MCP와 성공한 live session을 혼동하지 않습니다.
콘텐츠 계약으로 공개 문서 지키기¶
공개 제품의 일부인 문서에도 테스트가 필요합니다. 예를 들면 다음과 같습니다.
- 모든 P0 페이지가 지원 언어에 존재함;
- 다국어 내비게이션이 실제 파일만 가리킴;
- index가 홍보 글로 연결하기 전에 글이 존재함;
- 오래된 주장은 삭제하거나 compatibility라고 명시함;
- docs와 blog의 strict MkDocs build가 통과함.
작고 빠른 검사는 문구가 자주 바뀌는 SEO/GEO 작업에서 크롤링 가능한 구조를 지켜 줍니다.
FAQ¶
CLI에 프로젝트 관리를 추가하는 것뿐인가요?¶
아닙니다. 라우트 분류, 편집 안전, 컨텍스트 선택, 검증이라는 실행 가능한 검사와 상태 규칙입니다. 에이전트가 되돌리기 어렵거나 검토하기 힘든 결정을 내리는 지점의 모호함을 줄입니다.
모든 transcript를 저장해야 하나요?¶
아닙니다. 안정적인 프로젝트 사실, 선택한 작업 항목, 유용한 handoff만 저장하고 필요한 때 pull합니다.
가장 작은 개선은 무엇인가요?¶
라우트 표, 편집 전 검사, 검증 체크리스트부터 시작하세요. 복구나 독립 소유가 실제로 필요할 때만 solo harness나 팀 위임을 추가합니다.