피드로 돌아가기
Dev.toAI/ML
원문 읽기
Markdown Contract 기반 Skill 설계로 Human Review 병목 제거 및 에이전트 확장성 확보
Skills as invocation contracts, not code: how I keep review authority over agent work
AI 요약
Context
에이전트 구현체가 코드(Code-as-skill)로 정의될 때 발생하는 Human Review 부하와 Blind Diff-accepting 위험을 분석함. 구현 세부 사항과 호출 계약이 결합된 구조로 인해 에이전트의 코드 재생성 시마다 전체 로직을 재검토해야 하는 확장성 한계를 식별함.
Technical Solution
- Skill을 Markdown 기반의 Invocation Contract로 분리하여 구현체와 독립적인 리뷰 인터페이스 구축
- Frontmatter, Inputs, Work delegated, Failure modes의 4단계 구조를 통해 구현 세부 사항을 배제한 행위 정의
- 구현체(Python)를 Contract 하위의 교체 가능한 모듈로 처리하여 계약 변경 없는 코드 리팩토링 및 에이전트 재생성 허용
- ThreadPoolExecutor와 Agent tool 간의 구조적 동일성을 유지하여 환경에 구애받지 않는 결정론적 출력 및 CI 검증 체계 마련
- 모든 실행 제어권을 config/flags.yaml로 외부화하여 코드 수정 없는 런타임 동작 제어 및 감사 추적성 확보
- JS와 외부 참조를 제거한 Single HTML 리포트 형식을 채택하여 Byte-by-byte Diff가 가능한 리뷰 환경 구축
실천 포인트
- Skill 계약서에서 특정 라이브러리나 파일 경로 등 구현 세부 사항이 포함되었는지 검토 - 성공 경로 외에 구체적인 Failure Mode가 계약서에 명시적으로 정의되었는지 확인 - 기능 토글 및 환경 변수가 코드 내 if문이 아닌 외부 Config 파일로 완전히 분리되었는지 체크 - 에이전트가 생성한 코드의 Diff를 맹목적으로 승인하는 대신, 고정된 Contract 기반의 검증 프로세스 도입
태그