agents-best-practices는 에이전트 하네스를 설계·감사·리팩터링·설명하기 위한 제공자 중립 Agent Skill이다. Codex, Claude Code 같은 코딩 에이전트뿐 아니라 리서치, 지원, 운영, 영업, 법무, 의료, 교육 워크플로 에이전트에도 적용되는 런타임 원칙을 다룬다.
핵심 관점
이 스킬은 모델을 에이전트의 전부로 보지 않는다. 에이전트 하네스는 지시, 컨텍스트 빌더, 모델 호출, 도구 제안, schema validation, permission check, 실행 또는 승인 대기, observation, 다음 단계 결정으로 구성된 control plane이다.
instructions -> context builder -> model call -> tool proposal
-> validation -> permission decision -> execution/approval
-> observation -> next step/final answer주요 사용 사례
| 사용 사례 | 스킬이 돕는 내용 |
|---|---|
| MVP 에이전트 blueprint | 도메인에 맞는 최소 production-safe harness 설계 |
| 기존 하네스 audit | 무한 루프, 비용 폭증, compaction 실패, tool result 오염 진단 |
| 도구·권한 설계 | 넓은 run_command 대신 좁은 typed tool과 approval gate 설계 |
| 평가·관측성 | trace, launch gate, regression eval, incident response 구조화 |
| 컨텍스트·메모리 | compaction 후에도 목표, 승인, 산출물 상태를 잃지 않게 설계 |
어디에 적합한가
- 직접 에이전트 런타임을 만드는 플랫폼 팀
- MCP connector, skill, tool permission을 안전하게 설계해야 하는 조직
- “프롬프트만 고치기”에서 벗어나 실행 루프와 평가를 정비하려는 개발자
- Codex/Claude Code용 스킬로 에이전트 설계 리뷰를 반복하고 싶은 사용자
관련 문서
- agent-harness — AI 에이전트 성능을 결정하는 하네스 설계
- agent-skills — 에이전트 스킬 시스템 개요
- ai-agent-evaluation — 에이전트 평가 하네스 설계
- mcp — 에이전트와 외부 시스템을 연결하는 표준 프로토콜
참고 자료
- DenisSergeevitch/agents-best-practices — GitHub 공식 저장소