Agent Heuristic Design

• Agent Heuristic Design은 CLI tool이 agent에게 자기 자신을 가르치도록 만드는 출력·에러·도움말 설계 원칙
• Progressive --help, Error as navigation, Consistent output format 3기법으로 구성된 agent 자기학습 인터페이스
• 도구 사용법을 별도 학습 없이 반복 노출과 점진적 발견으로 습득시키는 agent UX 패턴
• 컨텍스트 절감과 자율 복구 능력을 동시에 확보하는 tool 출력 설계 원칙

해당 개념이 필요한 이유

• 도구 사용법을 매뉴얼로 사전 주입하면 컨텍스트의 큰 비중을 매뉴얼이 차지 → 실제 작업 토큰 부족
• 사람용으로 설계된 에러 메시지는 agent가 해석 후 추가 검색·시도 필요 → 호출 횟수와 시간 낭비
• 도구마다 출력 형식이 제각각이면 agent가 매번 파싱 패턴을 새로 추론 → 추론 품질 저하
• 호출 비용·실패 신호를 명시적으로 노출하지 않으면 agent가 비효율적 호출 패턴을 무한 반복

AS-IS — 정적 매뉴얼 + 인간용 에러 + 제각각 출력

sequenceDiagram
    autonumber
    participant A as Agent
    participant T as Tool
    Note over A: 시작 시 3000단어 매뉴얼 주입<br/>(컨텍스트의 30% 차지)
    A->>T: command 호출
    T-->>A: "Operation failed: code -127"
    Note over A: 에러 의미 추측<br/>매뉴얼 재참조
    A->>T: 다른 변형 시도
    T-->>A: 또 다른 형식의 에러
    Note over A: 학습 진전 없이 시행착오 반복

TO-BE — 점진적 발견 + 행동 지시 에러 + 일관 출력

sequenceDiagram
    autonumber
    participant A as Agent
    participant T as Tool
    Note over A: 시작 시 명령어 목록만<br/>(200단어, 한 줄 설명)
    A->>T: memory (인자 없이)
    T-->>A: "[error] usage: memory search|recent|store|..."
    Note over A: 사용법 자동 발견
    A->>T: memory search "foo"
    T-->>A: "결과...\n[exit:0 | 12ms]"
    Note over A: 비용·성공 패턴 학습<br/>다음 호출에 활용

휴리스틱 ①: Progressive --help Discovery

도구 정보를 한 번에 다 노출하지 않고, agent의 시도에 따라 3단계로 점진 공개한다. 컨텍스트 비용을 최소화하면서 필요한 순간에만 학습이 일어난다.

3단계 노출 구조

Level 0 — 대화 시작 시 동적 주입 (한 줄 요약 목록)

Available commands:
- cat — 텍스트 파일 읽기. 이미지는 'see', 바이너리는 'cat -b' 사용
- see — 이미지 보기
- grep — 패턴 필터링 (-i, -v, -c 지원)
- memory — 메모리 검색/관리
- clip — 외부 환경 운영 (샌드박스, 서비스)

Level 1 — 인자 없이 호출 시 사용법 반환

$ run("memory")
[error] memory: usage: memory search|recent|store|facts|forget
[exit:1 | 2ms]

Level 2 — 서브명령만 호출 시 파라미터 세부

$ run("memory search")
[error] memory: usage: memory search <query> [-t topic_id] [-k keyword]
[exit:1 | 2ms]

왜 효과적인가

비교 항목	정적 매뉴얼 주입	Progressive Discovery
시작 컨텍스트 비용	높음 (3000+ 단어)	낮음 (200 단어)
학습 시점	사전 (사용 전)	사후 (시도 후)
정보 정확도	매뉴얼 vs 실제 괴리 가능	실제 동작과 일치
Agent 행동	매뉴얼 재참조	자연스러운 시행

핵심은 사람이 새 CLI 도구를 배우는 방식과 동일하다는 점이다. 사람도 매뉴얼을 다 읽고 시작하지 않고, 명령어 입력 → 에러 → 사용법 학습 사이클을 거친다.

휴리스틱 ②: Error as Navigation

에러 메시지가 단순히 “실패했음”을 알리는 게 아니라, 다음에 무엇을 해야 하는지 정확히 지시해야 한다.

인간용 vs Agent용 에러 메시지

인간용 (전통적 CLI):

$ cat photo.png
cat: binary file (standard output)
→ 사람이 Google 검색, "PNG 어떻게 보지?"

Agent용 (Heuristic Design):

$ cat photo.png
[error] cat: binary image file (182KB). Use: see photo.png
→ agent가 즉시 'see photo.png' 호출

추가 예시

상황	좋은 에러 메시지
알 수 없는 명령어	[error] unknown command: foo Available: cat, ls, see, write, grep, memory, clip
잘못된 파일 타입	[error] not an image file: data.csv (use cat to read text files)
존재하지 않는 자원	[error] clip "sandbox" not found. Use 'clip list' to see available clips

설계 원칙

1. 현재 무엇이 잘못됐는지 정확히 명시
2. 즉시 실행 가능한 다음 명령어를 함께 제공
3. 정보 탐색이 필요한 경우 그 탐색 명령어를 안내

이 원칙이 Two-Layer Architecture의 바이너리 가드와 결합하면, 잘못된 호출이 즉시 올바른 호출로 이어진다.

휴리스틱 ③: Consistent Output Format

매 호출의 출력 끝에 동일한 형식의 메타데이터를 부착한다. 반복 노출을 통해 agent가 패턴을 자연스럽게 내재화한다.

표준 푸터 형식

실제 명령어 출력 내용
[exit:0 | 12ms]

두 필드의 학습 효과

Exit Code — Unix 표준, LLM 사전지식 활용

코드	의미	Agent의 학습
exit:0	성공	결과를 신뢰하고 다음 단계로
exit:1	일반 실패	인자/조건 재검토
exit:127	명령어 없음	다른 명령어 시도

Duration — 비용 인식 학습

시간	Agent 행동 변화
12ms	자유롭게 호출, 탐색용으로도 사용
3.2s	신중히 사용, 호출 전 명확한 의도 정립
45s	호출 횟수 최소화, 결과 캐싱 고려

누적 효과

세션이 길어질수록 agent는:

• 빠른 명령어로 탐색 → 비싼 명령어로 결정적 호출
• 실패 패턴을 빠르게 인지 → 재시도 횟수 감소
• exit code별 분기를 자동으로 적용 → && / || 활용 능숙

이는 별도 학습이나 프롬프트 추가 없이 반복 노출만으로 학습되는 행동 패턴이다.

세 기법의 시너지 — 학습 비용 vs 운영 비용

세 기법이 결합되면 학습 비용을 운영 중에 점진적으로 분산시킬 수 있다.

flowchart LR
    Start[대화 시작] --> L0[Level 0: 명령어 목록 200단어]
    L0 --> Try[Agent 시도]
    Try --> Err{에러 발생?}
    Err -->|Yes| Nav[Error as navigation:<br/>다음 행동 지시]
    Err -->|No| Foot[Consistent output:<br/>비용·성공 학습]
    Nav --> Try
    Foot --> Try
    Try --> Better[더 효율적인 호출 패턴]

기법	학습 시점	학습 비용 출처
Progressive --help	도구 사용 시도 시	실제 시도가 일어날 때만
Error as Navigation	실수했을 때	자연스러운 복구 비용에 동승
Consistent Output	매 호출	거의 무료 (메타데이터 한 줄)

안티패턴 — 자주 보이는 잘못된 사례

• 사전 매뉴얼 폭격: “도구 사용법” 5000자를 시스템 프롬프트에 주입 → 토큰 낭비
• 친근한 에러: “Oops! Something went wrong :(” → agent가 무엇을 할지 모름
• 포맷 일관성 부재: 도구마다 성공/실패 신호가 다름 → 매번 파싱 추론
• Stderr 침묵: 에러 본문을 stdout 한 줄로 요약 → 원인 파악 불가
• 숫자 코드만: Error: -127 → 의미 없음, “Use:” 같은 행동 지시 누락

적용 시 체크리스트

• 시작 시 주입되는 도구 정보가 한 줄 설명 위주로 짧은가
• 인자 없이 호출 시 사용법 자동 반환되는가
• 에러 메시지에 즉시 실행 가능한 다음 명령어가 포함되는가
• 알 수 없는 명령어에 대해 사용 가능한 명령어 목록을 함께 노출하는가
• 모든 호출 응답에 [exit:N | duration] 푸터가 일관되게 부착되는가
• duration 단위가 ms/s로 일관되며 비용 차이가 인지될 수 있게 표시되는가

관련 개념

• CLI-based Tool Calling — 이 휴리스틱이 적용되는 상위 도구 모델(메인 개념)
• Two-Layer Architecture — Error as Navigation이 실제로 구현되는 Layer 2의 4가지 메커니즘
• delta — 스트리밍 메타데이터 일반 개념

참고 문서

• I was backend lead at Manus — 원문 Gist
• Context Engineering for AI Agents (Manus 공식)
• agent-clip 소스 — internal/tools.go (명령어 라우팅)