iamfakeguru/agent-md

Production-grade agent directives for autonomous coding agents: Claude Code, Codex, Cursor, Windsurf, Aider.

agent-md – 코딩 에이전트를 위한 휴대용 계약

개요 – agent-md는 코드베이스 내에 공식적이고 강제적인 계약을 삽입하여 AI 코딩 어시스턴트(Claude Code, Codex, Cursor, Windsurf 등)가 가이드되고, 검증되며, 책임을 지도록 하는 언어 독립적인 소형 프레임워크입니다. 규칙 파일, git-hooks, 헬퍼 스크립트를 설치하여 자유 형식의 프롬프트를 재현 가능하고 감사 가능한 워크플로우로 전환합니다.

중요성 – LLM 기반 페어 프로그래머가 보편화됨에 따라 개발자는 모델이 실제로 무엇을 수행했는지 파악하기 어려워졌습니다. agent-md는 에이전트 지침에 대한 단일 진실 공급원(AGENT.md)을 제공하고 이를 강력한 검사(타입 체크, 린팅, 테스트 실행, 시각적 스크린샷)와 결합하여 필요한 증거가 제시될 때까지 모델의 작업 완료를 차단합니다.

핵심 개념

개념	역할	강제 방법
규칙 파일 (`AGENT.md`, `AGENTS.md`, `CLAUDE.md`)	스타일, 계획, 안전 등에 관한 사람이 작성한 가이드라인.	권고 사항 – 모델이 읽어야 하지만 자동으로 차단되지는 않음.
Hooks / 아티팩트	구체적인 검사(타입 체크, 린트, 테스트, 시각적 증거, 상태 업데이트)	에이전트별 훅 스크립트(예: `.claude/hooks/block-destructive.sh`) 또는 대체 git pre-commit 훅에 의해 강제됨.
메모리 파일 (`memory/*.md`)	세션 간 지속적인 전달 – 계획, 진행 상황, 검증 기준, 주의 사항.	훅이 파일 업데이트를 검증하며, 업데이트 누락 시 하드 차단 발생.
헬퍼 스크립트 (`.agent-md/bin/*`)	에이전트가 호출할 수 있는 소형 셸 유틸리티(헬퍼 발견, Playwright 스크린샷 실행, 진단 등).	모델이 직접 실행하며, 후속 훅에서 사용되는 결정론적 결과를 반환함.

설치 후 구성

your-project/
├─ AGENT.md               # 에이전트를 위한 단일 진실 공급원
├─ AGENTS.md              # Codex / Cursor / Windsurf 용 복사본
├─ CLAUDE.md              # Claude Code를 위해 AGENT.md를 가져오는 래퍼
├─ agent-md.toml.example  # 결정론적 검증 설정 템플릿
├─ .claude/               # Claude 전용 설정 및 훅
├─ .codex/                # Codex 전용 훅 및 설정
├─ .agents/skills/        # 네이티브 Codex 스킬 (verify, visual-evidence)
├─ .cursor/… .windsurf/…  # 해당 에이전트용 규칙 파일
├─ .agent-md/bin/         # 헬퍼 스크립트 (discover_helpers.sh, doctor.sh, …)
├─ memory/                # 지속적 상태 파일 (plan.md, progress.md, …)
└─ .githooks/pre-commit   # 선택적 범용 대체 훅

이 모든 것은 단일 curl … | bash 명령 또는 제공된 install.sh 스크립트를 통해 설치됩니다.

검증 작동 방식

검사 설정 – agent-md.toml.example을 agent-md.toml로 복사하고 typecheck, lint, test 및 시각적 아티팩트 요구 사항에 대한 명령을 입력합니다.
에이전트 실행 – 모델이 평소처럼 코드를 작성합니다.
훅 실행 – 모델이 완료를 알리면 적절한 훅이 설정된 명령을 실행합니다.
차단 또는 허용 – 명령이 실패하거나 필요한 시각적 증거가 누락/오래된 경우, 훅은 모델의 완료 단계를 중단하고 오류 메시지를 반환합니다. 모든 검사를 통과해야만 모델의 출력이 수락됩니다.

일반적인 워크플로우

# 1. 새 저장소에 설치
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bash

# 2. 프로젝트별 가이드라인으로 AGENT.md 편집
vim AGENT.md

# 3. 검증 명령 정의
cp agent-md.toml.example agent-md.toml
# 테스트 러너, 린터 등을 가리키도록 toml 편집.

# 4. Claude Code (또는 Codex, Cursor, …)로 코딩 시작
#    에이전트가 규칙을 확인하고 종료 시 훅이 실행됩니다.

# 5. UI 작업이 포함된 경우 스크린샷 캡처
./.agent-md/bin/playwright-capture.sh http://localhost:3000 .agent/visual/home.png
# 시각적 검사를 설명하는 마크다운 메모 작성

단계가 실패하면 훅이 명확한 메시지를 출력하고 모델은 작업을 다시 수행해야 합니다.

권장 대상

LLM 기반 코드 생성에 의존하며 재현 가능하고 감사 가능한 출력이 필요한 팀.
보안을 중시하는 개발자로, 파괴적인 Bash 명령을 차단하거나 상태 파일 업데이트를 보장하려는 경우.
UI를 구축하는 제품 팀으로, 단위 테스트 외에 시각적 회귀 증거가 필요한 경우.
오픈 소스 관리자로, AI 기여자에게 "계약"을 삽입하는 경량의 언어 독립적인 방법을 찾는 경우.

제한 사항(문서화된 내용)

규칙(AGENT.md)은 권고 사항이며, 훅만이 강제력을 가집니다.
강제력은 호스트 에이전트가 노출하는 이벤트로 제한됩니다(예: Cursor 및 Windsurf는 선택적 git-hook 대체만 가능).
Pre-commit 훅은 git commit --no-verify로 우회될 수 있습니다.
Bash 보안 훅은 가드레일일 뿐 완전한 샌드박스가 아닙니다.

개발 및 CI

테스트는 Bats(Bash Automated Testing System)로 작성되었습니다.
ShellCheck를 통한 린팅 및 훅 파일에 대한 JSON 검증을 수행합니다.
CI는 테스트 스위트, ShellCheck, 별칭 동기화 검사 및 설치 프로그램 스모크 테스트를 실행합니다.

라이선스

MIT – 자유롭게 사용, 수정 및 재배포 가능.

결론 – agent-md는 AI 코딩 어시스턴트와의 비구조화된 상호 작용을 계약 기반 프로세스로 전환하는 실용적이고 의존성이 낮은 툴킷입니다. 팀은 모델의 작업이 완료로 간주되기 전에 타입 체크, 테스트, 시각적 증명 및 상태 업데이트를 요구할 수 있습니다.