코딩 에이전트를 위한 휴대용 계약서.

agent-md는 하나의 출처-진실 규칙 파일, 저장소-로컬 훅을 설치합니다, 지속적인 작업 상태와 에이전트가 멈출 수 있도록 돕는 몇 가지 보조 스크립트 추측하며 그들의 작업을 증명하기 시작하세요.

솔직한 범위:

• 마크다운 규칙은 자문적 것입니다. 에이전트는 이를 읽고 따라야 합니다.
• 훅과 git 훅은 호스트 에이전트가 지원하는 경우 강제할 수 있습니다.
• 테스트, 타입 검사, 스크린샷, 증거 노트가 더 강력합니다 모델 자기 평가.

퀵스타트

기본적으로 Claude Code, Codex, Cursor, Windsurf 지원을 설치합니다.

네가 얻는 것들

핵심 아이디어

에이전트 안내는 두 가지 층으로 이루어집니다:

잊히거나 합리화할 수 있는 무언가가 산문에서 벗어나면 그리고 체크된 유물로 변했다.

런타임 수업 적용

이 저장소에 맞는 생산-에이전트 교훈은 계약으로 적용됩니다. 복사된 API 보일러플레이트가 아닙니다:

• 비용/맥락 규율 — 간결한 지침, 보조 발견, 그리고

agent-md

Portable contracts for coding agents.

agent-md installs one source-of-truth rules file, repo-local hooks, persistent task state, and a few helper scripts so agents can stop guessing and start proving their work.

Honest scope:

• Markdown rules are advisory. The agent has to read and follow them.
• Hooks and git hooks are enforceable where the host agent supports them.
• Tests, type-checks, screenshots, and evidence notes are stronger than model self-assessment.

Quickstart

# From inside your project directory
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bash

Installs support for Claude Code, Codex, Cursor, and Windsurf by default.

What You Get

your-project/
  AGENT.md                         # source of truth
  AGENTS.md                        # Codex / Cursor / Windsurf
  CLAUDE.md                        # Claude Code wrapper — imports AGENT.md via @AGENT.md (see #3)
  agent-md.toml.example            # deterministic verification config

  .claude/
    settings.json
    hooks/                         # Claude Code enforcement

  .codex/
    hooks.json
    hooks/                         # Codex hook wrappers

  .agents/skills/                  # native Codex skills
    agent-md-verify/
    visual-evidence/

  .cursor/rules/agent-md.mdc       # Cursor project rule
  .windsurf/rules/agent-md.md      # Windsurf workspace rule

  .agent-md/
    bin/
      discover_helpers.sh
      doctor.sh
      playwright-capture.sh

  memory/
    agents.md
    plan.md
    progress.md
    verify.md
    gotchas.md

  .githooks/pre-commit             # optional fallback for any agent

The Core Idea

Agent guidance has two layers:

If something can be forgotten or rationalized away, move it out of prose and into a checked artifact.

Runtime Lessons Applied

The production-agent lessons that fit this repo are applied as contracts, not as copied API boilerplate:

• Cost/context discipline — concise directives, helper discovery, and durable memory/ files instead of giant repeated prompts.
• Reliability — structured hook JSON, deterministic checks, destructive-command blocks, and explicit unverified-state warnings.
• Performance — bounded work slices, selective context loading, safe parallel tool use, and truncation warnings.
• Tool use — structured tool-result guidance, validation before execution, and clear helper boundaries.
• Output quality — tests, runtime evidence, visual artifacts, and independent/adversarial verification.

API-specific features such as prompt caching, streaming display, provider retries, idempotency keys, temperature tuning, and batch processing belong in the application or host runtime. agent-md tells