TracePact: 프로덕션 전에 AI 에이전트 툴 호출 회귀를 잡아내다

Source: Dev.to

TracePact가 하는 일

TracePact는 AI 에이전트를 위한 행동 테스트 프레임워크입니다. 텍스트 수준이 아니라 툴‑콜 수준에서 동작합니다.

1. 행동 계약 작성

import { TraceBuilder } from '@tracepact/vitest';

const trace = new TraceBuilder()
  .addCall('read_file', { path: 'src/service.ts' }, '...')
  .addCall('write_file', { path: 'src/service.ts', content: '...' })
  .addCall('run_tests', {}, 'PASS')
  .build();

// 읽기 후에 쓰기를 했나요?
expect(trace).toHaveCalledToolsInOrder([
  'read_file',
  'write_file',
  'run_tests'
]);

// 쉘을 사용하지 않았나요?
expect(trace).toNotHaveCalledTool('bash');

API 호출 없음. 토큰 사용 없음. 밀리초 단위로 실행됩니다.

2. 기록 및 재생

# 베이스라인 기록 (한 번, 실시간)
npx tracepact run --live --record

# API 호출 없이 재생 (즉시, 결정적)
npx tracepact run --replay ./cassettes

3. 실행 차이점(diff)으로 드리프트 감지

npx tracepact diff baseline.json latest.json --fail-on warn

샘플 출력

3 changes detected:
- read_file (seq 1) (removed)
+ write_file (seq 3) (added)
~ bash.cmd: "npm test" -> "npm run build"

Summary: 1 removed, 1 added, 1 arg changed

잡음이 많은 인자와 관련 없는 툴 필터링

npx tracepact diff baseline.json latest.json \
  --ignore-keys timestamp,requestId \
  --ignore-tools read_file

심각도 수준

• none – 동일함
• warn – 인자 변경
• block – 툴 추가/제거

CI에서 배포를 차단하려면 --fail-on 옵션을 사용하세요.

적합한 경우

• 코딩 에이전트 – 쓰기 전에 읽기, 종료 전에 테스트 실행, 제한된 파일 절대 편집 금지
• 운영 에이전트 – 재시작 전에 점검, 행동 전에 증거 확인
• 워크플로우 에이전트 – 변형 전 검증, 중복 부작용 방지
• 내부 어시스턴트 – 올바른 작업에 올바른 시스템 사용

덜 유용한 경우

순수 챗봇, 스타일 평가, 창의적 작업, 혹은 텍스트 출력만 중요한 시스템. TracePact는 행동 보장을 위한 것이며, 응답 품질을 평가하는 도구는 아닙니다.

IDE용 MCP 서버

TracePact는 Claude Code, Cursor, Windsurf와 함께 사용할 수 있는 MCP 서버를 제공합니다:

{
  "mcpServers": {
    "tracepact": {
      "command": "npx",
      "args": ["@tracepact/mcp-server"]
    }
  }
}

사용 가능한 툴: tracepact_audit, tracepact_run, tracepact_capture, tracepact_replay, tracepact_diff, tracepact_list_tests.

시작하기

npm install @tracepact/core @tracepact/vitest @tracepact/cli
npx tracepact init
npx tracepact

GitHub:

우리는 프롬프트나 모델 변경이 에이전트 행동을 조용히 깨뜨리면서도 출력은 괜찮아 보이는 상황을 방지하기 위해 이 도구를 만들었습니다. AI 에이전트를 테스트하고 있다면, 현재 툴‑콜 회귀를 어떻게 다루고 있는지 알려 주세요.