코딩 에이전트 (coding agents)를 위한 휴대 가능한 계약 (Portable contracts).
agent-md
단일 진실 공급원 (source-of-truth) 규칙 파일, 저장소 로컬 훅 (repo-local hooks), 지속적인 작업 상태 (persistent task state), 그리고 몇 가지 헬퍼 스크립트 (helper scripts)를 설치하여 에이전트가 추측을 멈추고 자신의 작업 내용을 증명하기 시작할 수 있도록 합니다.
솔직한 범위 (Honest scope):
- Markdown 규칙은 권고 사항 (advisory)입니다. 에이전트는 이를 읽고 따라야 합니다.
- 훅 (Hooks) 및 git 훅 (git hooks)은 호스트 에이전트가 지원하는 경우 강제 (enforceable)할 수 있습니다.
- 테스트 (Tests), 타입 체크 (type-checks), 스크린샷 (screenshots), 그리고 증거 노트 (evidence notes)는 모델의 자기 평가 (model self-assessment)보다 더 강력합니다.
# 프로젝트 디렉토리 내부에서
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bash
기본적으로 Claude Code, Codex, Cursor, 그리고 Windsurf에 대한 지원을 설치합니다.
your-project/
AGENT.md # 진실 공급원 (source of truth)
AGENTS.md # Codex / Cursor / Windsurf
...
에이전트 가이드는 두 개의 계층 (layers)을 가집니다:
| 계층 (Layer) | 목적 (Purpose) | 신뢰도 (Reliability) |
|---|
| 규칙 파일 (Rules files) | 판단, 계획, 스타일, 프로세스 | 권고 (Advisory) |
| 훅/아티팩트 (Hooks/artifacts) | 타입 체크, 테스트, 린트 (lint), 상태 업데이트, 시각적 증거 | 지원되는 경우 강제 가능 (Enforceable where supported) |
잊히거나 합리화되어 무시될 수 있는 것이 있다면, 산문 (prose)에서 제외하여 체크 가능한 아티팩트 (checked artifact)로 옮기십시오.
이 저장소에 적합한 프로덕션 에이전트 (production-agent) 교훈들은 복사된 API 보일러플레이트 (boilerplate)가 아닌 계약 (contracts)으로서 적용됩니다:
비용/컨텍스트 규율 (Cost/context discipline)— 거대한 반복 프롬프트 대신 간결한 지시 사항, 헬퍼 발견, 그리고 지속적인 memory/ 파일을 사용합니다. 신뢰성 (Reliability)— 구조화된 훅 JSON (hook JSON), 결정론적 체크 (deterministic checks), 파괴적 명령 블록 (destructive-command blocks), 그리고 명시적인 미검증 상태 경고 (unverified-state warnings). 성능 (Performance)— 제한된 작업 슬라이스 (bounded work slices), 선택적 컨텍스트 로딩 (selective context loading), 안전한 병렬 도구 사용 (safe parallel tool use), 그리고 절단 경고 (truncation warnings). 도구 사용 (Tool use)— 구조화된 도구-결과 가이드 (tool-result guidance), 실행 전 검증 (validation before execution), 그리고 명확한 헬퍼 경계 (helper boundaries). 출력 품질 (Output quality)— 테스트, 런타임 증거 (runtime evidence), 시각적 아티팩트 (visual artifacts), 그리고 독립적/적대적 검증 (independent/adversarial verification).
프롬프트 캐싱 (prompt caching), 스트리밍 디스플레이 (streaming display), 제공자 재시도 (provider retries), 멱등성 키 (idempotency keys), 온도 조절 (temperature tuning), 그리고 배치 처리 (batch processing)와 같은 API 특화 기능들은 애플리케이션 또는 호스트 런타임 (host runtime)에 속해야 합니다. agent-md는 프로젝트에서 이러한 선택 사항들을 사용할 때 코딩 에이전트 (coding agent)가 이를 문서화하고 검증하도록 지시합니다. 즉, 규칙 파일 (rules file)을 통해 제공자 (provider)의 동작을 강제하는 척하지 않습니다.
| 체크 항목 | Claude Code | Codex | Cursor / Windsurf / 기타 |
|---|
| Bash 안전성 | .claude/hooks/block-destructive.sh를 통한 강력한 차단 | .codex/hooks/pre-tool-use.sh를 통한 강력한 차단 | 지원되지 않음 |
| 종료 시 타입 체크/린트/테스트 | stop-verify.sh를 통한 강력한 차단 | .codex/hooks/stop.sh를 통한 지속 | 선택적 .githooks/pre-commit |
memory/progress.md 업데이트 | state-enforcement.sh를 통한 강력한 차단 | .codex/hooks/stop.sh를 통한 지속 | 선택적 .githooks/pre-commit |
| UI 시각적 증거 | 기본적으로 권고 사항, [visual].required = true일 때 강력한 차단 | Codex Stop 래퍼 (wrapper)를 통해 동일하게 적용 | 규칙을 통한 권고 사항 |
| 인근 테스트 없는 새로운 export | 권고 사항 | 규칙/스킬 (skills)을 통한 권고 사항 | 규칙을 통한 권고 사항 |
| 잘린 Bash 출력 | 권고 사항 | Codex PostToolUse를 통한 권고 사항 | 지원되지 않음 |
| 계획, 컨텍스트, 편집 안전성 | 권고 사항 | 권고 사항 | 권고 사항 |
Codex 훅 (hooks)은 실험적이며 다음 설정이 필요합니다:
[features]
codex_hooks = true
~/.codex/config.toml 파일 내에 작성하십시오.
# 지원되는 모든 에이전트
./install.sh .
# 특정 에이전트
...
설치 프로그램 (installer)은 기존의 최상위 규칙 파일들을 교체하기 전에 백업합니다. 기존의 memory/*.md 파일들은 절대 덮어쓰지 않습니다. 기존의 .claude/settings.json은 merge 또는 replace를 선택하지 않는 한 기본적으로 건너뜁니다.
휴리스틱 (Heuristics)도 유용하지만, 명시적인 명령이 더 좋습니다. 예시 설정 파일을 복사하여 프로젝트 체크 사항을 선언하십시오:
cp agent-md.toml.example agent-md.toml
[verify]
typecheck = "npx --no-install tsc --noEmit"
lint = "npx --no-install eslint ."
...
검사(checks)가 감지되지 않을 때, 훅(hooks)은 완료를 허용하지만 작업이 검증되지 않았음을 경고합니다.
UI 작업은 테스트 통과 이상의 것이 필요합니다. 스크린샷을 캡처하세요:
./.agent-md/bin/playwright-capture.sh http://localhost:3000 .agent/visual/home.png
그 다음 .agent/visual/home.md를 작성하세요:
:
# Visual Check
Changed files:
- src/app/page.tsx
...
엄격한 시각적 훅(strict visual hook)은 파일 이름으로 참조되는 최신의 비어 있지 않은 이미지와 필수 필드를 포함하는 최신의 비어 있지 않은 마크다운(markdown) 파일을 요구합니다.
memory/
는 세션 간의 지속 가능한 핸드오프(handoff) 표면입니다:
agents.md
— 활성 에이전트(active agents), MCPs, 기술 스택(tech stack), 툴링(tooling)
plan.md
— 매크로 설계(macro design) 및 버티컬 슬라이스(vertical slices)
progress.md
— 현재 작업, 완료된 작업, 백로그(backlog), 차단된 작업(blocked work)
verify.md
— 완료 정의(definition of done)
gotchas.md
— 인간에 의해 이미 수정된 실수들
상태 훅(state hook)은 소스 파일은 변경되었으나 memory/progress.md가 변경되지 않은 경우 완료를 차단합니다.
agent-md
는 일반 헬퍼 스크립트(helper scripts)와 Codex 네이티브 스킬(Codex-native skills)을 의도적으로 분리합니다.
.agent-md/bin/*
은 어떤 에이전트든 실행할 수 있는 셸 헬퍼(shell helpers)입니다. .agents/skills/<name>/SKILL.md
는 네이티브 Codex 스킬입니다.
헬퍼를 발견하려면:
./.agent-md/bin/discover_helpers.sh
./.agent-md/bin/doctor.sh
$agent-md-verify 또는 $visual-evidence를 사용하여 Codex 스킬을 사용하세요.
- 규칙 파일(rules file) 자체만으로는 판단을 강제할 수 없습니다.
- 훅(hooks)은 호스트 에이전트(host agent)에 의해 노출된 이벤트만 다룹니다.
- 프리 커밋 훅(Pre-commit hooks)은
git commit --no-verify로 우회할 수 있습니다.
- Bash 안전 훅(safety hooks)은 가드레일(guardrails)이지 샌드박스(sandbox)가 아닙니다.
- Cursor 및 Windsurf는 규칙(rules)과 선택적인 git-hook 폴백(fallback)을 제공받으며, 이 저장소로부터 네이티브 런타임 강제(native runtime enforcement)를 받지는 않습니다.
bats tests/
shellcheck .claude/hooks/*.sh .codex/hooks/*.sh .agent-md/bin/*.sh .githooks/pre-commit install.sh
CI는 Bats, ShellCheck, JSON 검증, 에일리어스 동기화(alias-sync) 체크 및 설치 프로그램 스모크 테스트(installer smoke tests)를 실행합니다.
MIT.