agents-best-practices: Codex와 Claude Code용 에이전트 하니스 설계 모범 사례 스킬

9bow · 6월 22, 2026, 1:30오전

agents-best-practices 소개

AI 에이전트를 실제 시스템에 붙여 일을 시키려고 하면, 모델 자체보다 그 주변을 둘러싼 런타임(runtime) 에서 문제가 생기는 경우가 많습니다. 도구를 무한정 호출하거나, 컨텍스트가 압축되며 진행 중이던 승인 상태를 잃거나, 어떤 결정을 왜 내렸는지 추적할 수 없는 일이 대표적입니다. agents-best-practices는 이런 런타임 수준의 문제를 다루기 위해, 에이전트 하니스(harness)를 설계·점검·리팩터링하는 방법을 모은 ** 에이전트 스킬(Agent Skill)** 입니다.

이 스킬은 특정 모델 제공자에 종속되지 않는 프로바이더 중립(provider-neutral) 을 지향하며, Codex와 Claude Code를 비롯해 SKILL.md 규격을 읽는 여러 에이전트 런타임에서 동작합니다. 저자는 이 스킬이 코딩 에이전트에만 한정되지 않고 리서치, 지원, 운영, 영업, 재무, 데이터 분석, 법무·의료 워크플로 등 동일한 런타임 규율 이 필요한 모든 에이전트에 적용된다고 설명합니다.

스킬의 중심 문제의식은 한 문장으로 요약됩니다. "모델은 행동을 제안하고, 하니스가 검증·승인·실행·기록한 뒤 관찰 결과를 돌려준다" 는 것입니다. 즉 모델을 감사받지 않는 실행 주체로 두지 않고, 애플리케이션 코드가 통제하는 제어 평면(control plane)을 갖추는 것이 목표입니다.

agents-best-practices의 핵심 루프

agents-best-practices가 권장하는 하니스는 모델 호출을 하나의 단계로만 포함하는 루프입니다. 흐름은 지시·작업 입력 → 컨텍스트 구성 → 모델 호출 → 도구 호출 제안 → 스키마 검증 → 권한 확인 → 실행 또는 승인 대기 → 구조화된 관찰 결과 → 다음 단계 또는 최종 답변 으로 이어집니다. 여기서 핵심은 검증과 권한 확인을 모델이 아니라 하니스가 담당 한다는 점입니다.

이 원칙을 저자는 여덟 가지 런타임 규율로 정리합니다. 그중 핵심은 다음과 같습니다. 하니스가 행동의 주체이며 모델은 제안만 한다는 것, 모든 도구 호출은 거부·타임아웃·잘못된 인자·중단까지 포함해 반드시 결과(관찰)를 남긴다는 것, 그리고 읽기·초안·쓰기·외부 통신·금융·파괴적·권한 상승 같은 위험 등급에 따라 권한 경로를 다르게 둔다는 것입니다. 높은 위험을 가진 부수효과는 초안과 커밋을 분리하고, 승인 기록을 프롬프트 바깥에 남기도록 합니다.

또한 장시간 실행되는 작업에는 단계·시간·토큰·비용·도구 호출 예산을 두고, 컨텍스트는 무작정 쌓지 않고 필요한 만큼만 구성하며 신뢰 경계를 표시 합니다. 반복되는 실패는 프롬프트에 같은 조언을 덧붙이는 대신, 검증기·도구·문서·평가(eval)·정책 같은 하니스 기능으로 바꿔 해결합니다.

agents-best-practices를 쓰는 세 가지 방법

스킬은 대화가 에이전트 아키텍처, 하니스 설계, 도구 권한, 플래닝 모드, 워크플로 오케스트레이션, 컨텍스트·메모리, 관측성, 평가, 프롬프트 캐싱 같은 주제에 닿으면 활성화됩니다. 저자는 대표적인 세 가지 사용 방식을 제시합니다.

첫째, MVP 에이전트 청사진 생성 입니다. 도메인을 주면, 막연한 모범 사례 나열이 아니라 가장 작은 프로덕션 안전 하니스를 설계해 줍니다. 예를 들어 갱신 위험을 분석하는 에이전트라면 승인 게이트가 있는 단순한 루프와 최소한의 타입드 도구, 그리고 과거 계정 20건에 대한 트레이스 검토와 초안 행동 80% 이상 수용 같은 출시 게이트를 함께 제안합니다. 관련 자료는 저장소의 references/mvp-agent-blueprint.md입니다.

둘째, 기존 하니스 감사 입니다. 이미 동작하는 에이전트가 불안정하거나 비싸거나 디버깅하기 어렵다면, 실패 지점을 런타임 수준에서 진단하고 수정 순서를 제시합니다. 예컨대 루프 예산 부재, 압축 과정의 승인 상태 유실, 무한정 커지는 도구 결과, 이벤트 트레이스 부재 같은 문제를 짚고, 예산 추가 → 상태 외부 저장 → 압축 시 활성 상태 복원 → 평가 추가의 순서로 고치도록 안내합니다.

셋째, 도구·권한·커넥터 설계 입니다. send_message, write_database, run_command 같은 광범위한 도구를 노출하는 대신, 각 동작을 좁은 타입드 도구로 감싸고 위험 등급으로 분리합니다. 읽기는 범위가 한정되면 자율 실행을 허용하고, 외부 쓰기·배포·파괴적 동작·권한 상승·금융 동작은 모델 바깥의 승인 기록을 요구합니다.

agents-best-practices의 구성과 설치

스킬은 SKILL.md 진입점과 references/ 디렉토리로 이루어집니다. references/ 에는 agentic-loop.md(루프 불변식·예산·종료 규칙), tools-and-permissions.md(타입드 도구·위험 등급·승인), context-memory-compaction.md(컨텍스트·메모리·압축), security-evals-observability.md(가드레일·트레이싱·평가) 등 주제별 문서가 들어 있습니다.

설치는 호환 에이전트용 skills 도구를 쓰거나 직접 클론하면 됩니다.

# skills 도구 사용 (사용자 레벨에 전역 설치)
npx skills add DenisSergeevitch/agents-best-practices -g

# 또는 Claude Code 사용자 레벨에 직접 클론
mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "$HOME/.claude/skills/agents-best-practices"

Codex의 경우 ${CODEX_HOME:-$HOME/.codex}/skills/ 에 클론합니다. 스킬의 권장사항은 OpenAI, Anthropic, OpenAI 호환 API, MCP, 외부 커넥터 워크플로의 공통 프로덕션 하니스 패턴을 종합한 것으로, 출처는 저장소의 references/source-links.md에 정리되어 있습니다.

agents-best-practices의 라이선스

agents-best-practices는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

agents-best-practices 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~