コーディングエージェント向けのポータブル契約。

agent-md は1つのソース・オブ・トゥルースルールファイル、リポジトリローカルフックをインストールします。 永続的なタスク状態と、エージェントが停止できるいくつかのヘルパースクリプト 推測して、自分の仕事を証明し始めましょう。

正直な範囲:

• マークダウンのルールはあくまで助言的なものです。エージェントはそれを読み、従わなければなりません。
• フックとgitフックは、ホストエージェントがサポートしている場合に強制可能です。
• テスト、型式チェック、スクリーンショット、証拠ノートはより強力です モデルの自己評価。

クイックスタート

Claude Code、Codex、Cursor、Windsurfのサポートをデフォルトでインストールします。

何が手に入るか

核心的なアイデア

エージェントガイダンスには2つの層があります:

忘れられたり理屈で消せるものがあれば、散文から外しましょう そしてチェックされたアーティファクトに変わった。

ランタイムの教訓が適用される

このリポジトリに適合する生産エージェントの教訓は契約として適用されます。 コピーされた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