행동을 파일로 만들면 무엇이 검증되는가

이 문서는 GitHub 저장소 루트를 한 시점의 불변 커밋으로 고정한 정적 검토다. README는 프로젝트 주장 입력일 뿐 진실 원장도 번역 대상도 아니다.

• 경로정확한 호스트 github.com, 객체 종류 repository, canonical owner/repo braintrustdata/agentbehavior.
• 시각2026-08-28 04:02:28Z–04:07:59Z, 331초. 메타데이터가 확인한 기본 브랜치는 main.
• REST28요청, 24×200, 4×401, 응답 본문 1,269,413 bytes. API 버전 2026-03-10을 발견 후 명시.
• Bare GitGET info/refs 31 + POST upload-pack 31 = 62 HTTP 요청. 59 objects(1 commit, 28 tree, 30 blob), uncompressed 168,735 bytes.
• 금지 준수checkout/worktree/install/build/test/run/import/benchmark/container/hooks/submodule/LFS/filter/textconv 전부 0회.

원본: https://github.com/braintrustdata/agentbehavior · 공개 원장: evidence/index.json · 배달 영수증: delivery-receipt.json

핵심은 “정책 엔진”이 아니라 “행동 명세 파일 + 구조 검증”이다. 다음 네 문장만 기억해도 된다.

가장 작은 명세

---
name: source-grounding
description: Require primary evidence before a material conclusion.
---

# Source grounding

결론 전 원자료를 확인하고, 확인하지 못한 부분은 불확실성으로 남긴다.

구조 근거: specification L14–90. 구현은 name 최대 64자, description 최대 1,024자를 적용한다: index.ts L5–9.

도입 전 네 가지 guardrail

1. spec에 origin·scope·commit을 함께 저장하고 third-party spec은 trust review를 거친다.
2. validator 성공을 “좋은 행동” 또는 “모델이 따름”으로 번역하지 않는다.
3. remote gateway host를 allowlist하고 금융·지원·trajectory payload를 분류·redact한다.
4. packed CLI, permission race, malformed filesystem, judge calibration을 별도 pilot에서 실행 검증한다.

배포 manifest가 말하는 진입점은 ESM library dist/index.mjs와 binary agentbehavior → dist/cli.mjs다. 소스 기준 실제 명령은 validate, list, explain 세 가지다.

Manifest: package.json L5–35 · 명령 dispatch: cli.ts L46–59 / L197–234.

검증기가 실제로 확인하는 것

• 정확한 파일명 BEHAVIOR.md와 정확한 위치 .agents/behaviors/<name>.
• frontmatter delimiter, YAML parse, mapping 여부.
• name 필수·정규식·길이·directory match.
• description 필수·길이, metadata가 있으면 mapping.
• 프로젝트 발견 시 immediate child directory만 정렬하고 비-directory entry는 warning.

확인하지 않는 것

• 본문의 행동 품질, 모순, 실행 가능성, 모델 순응.
• 조직/사용자/프로젝트 scope 간 우선순위·상속·병합.
• frontmatter license의 record 전달. 파서는 허용하지만 BehaviorRecord에는 name/description/metadata/location/body만 남긴다.

저장소는 네 층이다: 규범 문서, filesystem/YAML validator, CLI adapter, 그리고 행동을 prompt·deterministic logic·eval judge에 연결하는 예제.

Core control flow

main(argv)이 명령을 분기하고 validatePath가 path 종류를 판별한다. 프로젝트라면 .agents/behaviors의 바로 아래 디렉터리를 정렬한 뒤 각 파일을 읽고 frontmatter를 파싱한다. 모든 진단이 text/JSON 출력과 exit code를 결정한다. index.ts L487–677

Example agent data flow

financial/support 예제는 먼저 domain input에서 typed deterministic report를 만든다. 그 다음 behavior body와 JSON report를 model messages에 넣고 Braintrust gateway가 최종 문장을 생성한다. 즉, “행동 파일이 계산한다”가 아니라 “결정론적 처리 + 행동을 포함한 모델 문장화”다.

Eval judge flow

tax 예제 judge는 behavior의 각 H2를 meta-behavior로 보고 trajectory에서 occurrence와 citation을 요구한다. citation event ID와 위반 문구를 검증한 뒤 occurrence → meta-behavior → file verdict를 결정론적으로 접는다. 모델 응답 구조가 잘못되면 한 번 repair retry가 있다. judge.ts L49–88

아래는 저장소가 제시하는 개발·검증 경로를 재구성한 것이다. 이 dossier는 어느 명령도 실행하지 않았고 dependency를 설치하지 않았다.

# 저장소 루트 — 프로젝트 문서가 제시하는 경로
mise install
pnpm install --frozen-lockfile

# 구조 검증 CLI 예시
pnpm build
pnpm exec agentbehavior validate .

# 개발자 작업
pnpm check
pnpm test
pnpm build

# package 범위
pnpm --filter agentbehavior test
pnpm --filter agentbehavior build

전제는 pnpm 10.33, Node ≥20, Vite Plus다. root preinstall은 루트에서 pnpm이 아닌 user agent를 거부한다. 문서 deploy workflow는 Node 24와 frozen lockfile install 뒤 Mint export를 수행한다.

행동 모델

spec은 모델에 넣는 단순 “추가 prompt”보다, review·eval·prompt alignment의 source of truth를 목표로 한다. 본문은 자유 형식이라 한 파일에 여러 관련 행동을 담을 수 있다. 권장 차원인 intent/evidence/decision/execution/recovery/failure는 읽기·작성 프레임이지 validator 규칙이 아니다.

Discovery와 scope

문서는 project/user/organization scope를 예시하지만 bundled validator는 전달한 프로젝트의 local directory만 발견한다. precedence·inheritance·merge 필드가 없으므로 multi-scope 합성은 client 책임이다.

확장 지점

• 자유 형식 Markdown body와 optional companion references.
• custom metadata mapping.
• CLI JSON 출력으로 editor/CI/registry에 연결.
• client가 provenance·scope·version을 저장하고 browse/review/eval UI 제공.
• 예제 judge의 injected completion callback, model/base URL options.

테스트가 존재하는 범위

정적 test source는 valid/invalid schema, missing/case-variant file, YAML error, record filtering, CLI JSON/exit, deterministic reports, citation validation, verdict fold, repair retry, empty trace를 다룬다. 그러나 이번 workflow에서는 실행 0회다.

• 정적 확인문서 deploy workflow는 third-party actions를 immutable commit SHA로 고정하고 Pages에 배포한다.
• 외부 확인고정 커밋에는 성공한 Push on main run과 10개의 성공 CodeQL check가 반환됐다.
• 주의그 checks는 package build/test 이름이 아니다. successful CI를 곧바로 library runtime PASS로 읽을 수 없다.
• 릴리스package는 0.1.0과 prepublish build를 선언하지만 GitHub tags/releases는 비어 있다.
• 유지보수캡처 시 repo 생성 후 약 81일, 마지막 code push 후 30일, contributors response는 9/6/1 기여의 세 계정이다.

별 303, fork 6은 관심 신호일 뿐 품질 증거가 아니다. open issue/PR sample은 0이었지만 작은·젊은 저장소라는 맥락을 함께 봐야 한다.

자격증명과 outbound

예제 gateway는 BRAINTRUST_API_KEY를 bearer header에 넣고 설정 가능한 base URL로 messages를 전송한다. behavior body뿐 아니라 source artifact 이름·금액, ticket conversation·error, eval trajectory가 payload가 될 수 있다. endpoint override를 사용자 입력에 열어 두면 credential exfiltration 경계가 된다.

알 수 없는 보안 상태

고정 blob 261eeb9e…5c64와 GitHub metadata는 Apache-2.0으로 일치한다. 이 공개물은 저장소 코드나 README 완역이 아니라 원본 분석·메타데이터·해시·링크 disposition이며, 라이선스 전문을 evidence에 보존한다.

• LicenseApache License 2.0, permissive. 법률 자문 아님.
• NOTICE고정 트리에 NOTICE 파일 없음.
• Attributioncanonical repository와 immutable commit을 dossier/ledger/receipt에 기록.
• MediaREADME authored media occurrence 0건. remote subresource 0건.
• Decisionprivacy/license/sanitizer prerequisite를 만족하는 경우 publication allow.

공개 evidence의 LICENSE.txt · 고정 LICENSE

프로젝트가 말한 것, 코드가 정적으로 뒷받침한 것, 테스트가 존재하는 것, GitHub가 외부 확인한 것, 그리고 추론을 분리했다. 실행 관찰 증거는 0건이다.

저장소 루트 README는 번역하지 않았다. 대신 원문에 작성된 링크 17건을 고정 blob에서 추출해 동일 순서로 보존했다. 상대 저장소 경로는 분석 커밋으로 pin했고 외부 링크는 작성된 목적지를 유지했다.

1. 01DocumentationREADME L5 · Agent behavior
2. 02SpecificationREADME L5 · Agent behavior
3. 03QuickstartREADME L5 · Agent behavior
4. 04ExamplesREADME L5 · Agent behavior
5. 05`primary-source-tax-research`README L58 · What a behavior spec looks like
6. 06quickstartREADME L62 · Get started
7. 07`writing-agent-behavior`README L62 · Get started
8. 08`packages/agentbehavior`README L64 · Get started
9. 09examplesREADME L72 · Get started
10. 10agentbehavior.devREADME L76 · Documentation
11. 11SpecificationREADME L78 · Documentation
12. 12QuickstartREADME L79 · Documentation
13. 13Client implementation guideREADME L80 · Documentation
14. 14BasisREADME L84 · Contributing
15. 15BraintrustREADME L85 · Contributing
16. 16CONTRIBUTING.mdREADME L86 · Contributing
17. 17LICENSEREADME L90 · License

GitHub chrome과 이 dossier가 새로 만든 인용 링크는 authored occurrence 집계에서 제외된다. 이미지·picture source occurrence는 0건이며 repository-origin active content는 실행되지 않았다.

검토 범위

tree 102 entries(75 blobs, 27 trees)는 truncated:false였다. 그중 30 substantive files, 163,316 bytes, 4,322 lines를 전부 검사했다. core package의 manifest와 네 src/test 파일, 주요 spec/client docs, 4 behavior examples, 3 example flows, 5 test surfaces, docs CI, root manifest·license·contributing을 포함한다.

의도적 미확인

• dependency install, package build, test pass, packed dist, npm registry 배포.
• 실제 model 품질·judge calibration·gateway latency/availability/retention.
• 관리자 전용 branch protection과 scanning alert 현황.
• 저장소 밖 제품의 user/org scope precedence와 registry 운영.
• 로그인 실브라우저: Aside daemon, in-app backend, Chrome extension 경로가 각각 독립적으로 불가했다.

다음 likely break

pilot에서 먼저 검증할 것

1. packed binary로 valid/invalid/permission-race fixture를 실행.
2. license field를 API consumer가 필요로 하는지 결정.
3. scope merge 규칙과 provenance schema를 client에 명시.
4. gateway allowlist·redaction·data retention을 threat model로 고정.
5. 사람이 라벨링한 trajectory set으로 judge false positive/negative를 측정.

Capture 054acc99c449e82f0a2177dc2fc2b949 · commit 1866cffb530c93412719b7d3e243612a11bedf97 · tree 48bbf2add3a8bcffb4b74e9e1f67b3fd3da1a304 · runtime confidence unknown.