agent-harness-construction

name	agent-harness-construction
description	더 높은 완료율을 위해 AI 에이전트의 액션 공간, 도구 정의, 관측 포맷을 설계하고 최적화합니다.
origin	ECC

에이전트 하니스 구성

에이전트가 계획하고, 도구를 호출하고, 오류에서 복구하고, 완료 상태로 수렴하는 방식을 개선할 때 이 스킬을 사용합니다.

핵심 모델

에이전트 출력 품질은 다음에 의해 제한됩니다.

1. 액션 공간 품질
2. 관측 품질
3. 복구 품질
4. 컨텍스트 예산 품질

액션 공간 설계

1. 안정적이고 명시적인 도구 이름을 사용합니다.
2. 입력은 스키마 우선, 좁은 범위로 유지합니다.
3. 결정론적인 출력 형태를 반환합니다.
4. 격리가 불가능한 경우가 아니라면 만능 도구는 피합니다.

세분화 규칙

• 고위험 작업(배포, 마이그레이션, 권한)은 마이크로 도구를 사용합니다.
• 일반적인 편집/읽기/검색 루프는 중간 크기 도구를 사용합니다.
• 왕복 오버헤드가 지배적 비용일 때만 매크로 도구를 사용합니다.

관측 설계

모든 도구 응답은 다음을 포함해야 합니다.

• status: success|warning|error
• summary: 한 줄 결과
• next_actions: 실행 가능한 후속 조치
• artifacts: 파일 경로 또는 ID

오류 복구 계약

모든 오류 경로는 다음을 포함해야 합니다.

• 근본 원인 힌트
• 안전한 재시도 지침
• 명시적 중단 조건

컨텍스트 예산 운영

1. 시스템 프롬프트는 최소화하고 불변으로 유지합니다.
2. 큰 가이드는 필요 시 로드하는 스킬로 이동합니다.
3. 긴 문서를 그대로 넣기보다 파일 참조를 우선합니다.
4. 임의 토큰 임계값이 아니라 단계 경계에서 압축합니다.

아키텍처 패턴 가이드

• ReAct: 경로가 불확실한 탐색형 작업에 적합
• Function-calling: 구조화되고 결정론적인 흐름에 적합
• Hybrid(권장): ReAct 계획 + 타입화된 도구 실행

벤치마킹

다음을 추적합니다.

• 완료율
• 작업당 재시도 횟수
• pass@1, pass@3
• 성공 작업당 비용

안티패턴

• 의미가 겹치는 도구를 너무 많이 두는 것
• 복구 힌트 없는 불투명한 도구 출력
• 다음 단계 없이 오류만 반환하는 출력
• 관련 없는 참조로 컨텍스트를 과부하시시키는 것