Портативные контракты на кодировочные агенты.

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