AgentMap

AgentMap 会把 AGENTS.md、CLAUDE.md、GEMINI.md 维护成一份紧凑、基于证据的项目地图，供 coding agents 使用。

它是静态扫描器和 Markdown 维护工具。它不执行项目命令，不替代测试或 CI，不把任意文档散文总结成规则，不默认创建 planning files，也不会覆盖托管区块之外的人工内容。

默认文档是英文：README.md。

AgentMap 生成什么

AgentMap 把 AGENTS.md 作为 canonical shared instruction file，并为使用自己上下文文件名的工具生成 thin adapter。

AGENTS.md   = canonical shared agent rules
CLAUDE.md   = imports AGENTS.md + Claude-specific notes
GEMINI.md   = imports AGENTS.md + Gemini-specific notes

Adapter 模板：

# CLAUDE.md

@AGENTS.md

## Claude Code Notes

- When a user explicitly requests a Claude workflow or skill, follow that workflow first.
- Do not create additional planning files unless the user asks.
- Preserve user changes and avoid destructive git operations unless explicitly requested.

# GEMINI.md

@./AGENTS.md

## Gemini CLI Notes

- When a user explicitly requests a Gemini workflow or skill, follow that workflow first.
- Do not create additional planning files unless the user asks.
- Preserve user changes and avoid destructive git operations unless explicitly requested.

安全模型

agentmap scan、agentmap init、agentmap update、agentmap check 默认都是静态操作。

• 只读取 allowlisted project files。
• 在 1.0.0 中，high-confidence command 和 setup 生成主要支持 JavaScript/TypeScript 项目。
• 不运行 npm、pnpm、cargo、go、gradle 或项目脚本。
• 不读取 .env*、credential directories、binary files、dependency folders、build outputs、caches、VCS folders 或 large logs。
• 不跟随解析到 repository root 外部的 symlink。
• 把 README 和 docs 文本当作 untrusted input。
• 文档文件只用于 path-first documentation index。
• 只有 high-confidence facts 会写入正常 instruction sections。
• Medium/low-confidence findings 会进入 Needs Confirmation。

托管区块

AgentMap 只重写已知 managed blocks：

<!-- agentmap:start commands -->
<!-- agentmap:meta {"schema":1,"generator":"agentmap","generatorVersion":"1.0.0","block":"commands","sources":["package.json"],"sourceFingerprint":"sha256:...","bodyHash":"sha256:..."} -->
...
<!-- agentmap:end commands -->

sourceFingerprint 用于检测来源文件变化。bodyHash 用于检测 managed block 内部是否被人工编辑。如果 managed block 被人工编辑，agentmap update --write 会拒绝覆盖，除非传入 --force-managed。

持久配置

.agentmap.toml 是可选文件。agentmap scan 不会创建它。之后当用户确认/忽略 generated assumptions，或配置持久默认值时，AgentMap 可以创建它。

tool = "agentmap-instructions"
schema = 1
version = 1

[needsConfirmation]
confirmed = ["NC001"]
ignored = ["NC004"]

[targets]
files = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]

[profile]
default = "standard"

如果 .agentmap.toml 不包含 tool = "agentmap-instructions"，AgentMap 不会把它当作自己的配置。

配置字段说明：

• tool：必填签名。必须精确等于 "agentmap-instructions"；否则该文件会被忽略，避免和其他 AgentMap 工具冲突。
• schema：配置 schema 版本。本版本使用 1。
• version：用户维护的配置版本。AgentMap 会保留它，供人工识别和未来迁移使用。
• [needsConfirmation].confirmed：团队已经确认的 generated assumption 稳定 ID。确认后的 ID 不再出现在生成的 Needs Confirmation 和 check warning 中。
• [needsConfirmation].ignored：团队决定忽略的 generated assumption 稳定 ID。忽略后的 ID 同样不会出现在生成内容和 warning 中。
• [targets].files：当没有传入 --targets 时，init、update、check 使用的默认 target files。合法值是 AGENTS.md、CLAUDE.md、GEMINI.md。
• [profile].default：当没有传入 --profile 时，init、update、check 使用的默认生成 profile。合法值是 standard 和 minimal。

CLI 参数优先级高于 .agentmap.toml。例如 agentmap init --targets AGENTS.md --profile minimal 会覆盖 [targets].files 和 [profile].default。

AgentMap 永远不会在 .agentmap.toml 中存储 secrets、原始仓库正文、日志、环境变量值或大型生成内容。

命令

agentmap --version

打印 CLI 版本。

示例：

agentmap --version

输出：

1.0.0

agentmap scan

扫描当前仓库并打印人类可读摘要。这个命令不写文件。

示例：

agentmap scan

输出：

Project: TypeScript/JavaScript monorepo (high)
Package manager: pnpm (high)
Commands: pnpm lint, pnpm test, pnpm build
Docs: README.md, docs/architecture.md, docs/api.md
Needs confirmation: 0

agentmap scan --json

以 JSON 输出 scan model，适合调试、CI integration 或 editor integration。

示例：

agentmap scan --json

输出：

{
  "schema": 1,
  "project": {
    "value": "TypeScript/JavaScript monorepo",
    "confidence": "high",
    "evidence": ["package.json", "pnpm-workspace.yaml"],
    "sourceType": "structured"
  },
  "packageManager": {
    "value": "pnpm",
    "confidence": "high",
    "evidence": ["package.json:packageManager", "pnpm-lock.yaml"],
    "sourceType": "structured"
  },
  "commands": [
    {
      "name": "test",
      "command": "pnpm test",
      "group": "test",
      "confidence": "high",
      "evidence": ["package.json:scripts.test"],
      "sourceType": "structured"
    }
  ],
  "needsConfirmation": []
}

agentmap scan --explain

解释 AgentMap 为什么生成或跳过某些内容。

示例：

agentmap scan --explain

输出：

Package manager:
  Detected: pnpm
  Confidence: high
  Evidence:
    - package.json:packageManager
    - pnpm-lock.yaml
  Generated:
    - Setup: Use pnpm

Commands:
  pnpm test
  Confidence: high
  Evidence: package.json:scripts.test
  Destination: Common Commands

agentmap init --dry-run

预览 AgentMap 会创建的文件。这个命令不写文件。

示例：

agentmap init --dry-run

输出：

AgentMap init dry-run

--- AGENTS.md ---
# AGENTS.md

## Scope

This file applies to the entire repository.

...

--- CLAUDE.md ---
# CLAUDE.md

@AGENTS.md

...

--- GEMINI.md ---
# GEMINI.md

@./AGENTS.md

...

agentmap init --write

创建 AGENTS.md、CLAUDE.md、GEMINI.md。

示例：

agentmap init --write

输出：

Created AGENTS.md, CLAUDE.md, GEMINI.md

如果目标文件已经存在且没有 AgentMap managed blocks，write mode 会拒绝替换：

AGENTS.md already exists without managed blocks; run --dry-run and adopt manually.

agentmap init --targets AGENTS.md,CLAUDE.md,GEMINI.md

选择要创建或预览的 target files。

示例：

agentmap init --dry-run --targets AGENTS.md,CLAUDE.md

输出：

AgentMap init dry-run

--- AGENTS.md ---
# AGENTS.md

...

--- CLAUDE.md ---
# CLAUDE.md

@AGENTS.md

...

如果请求 adapter，但没有现有或目标中的 AGENTS.md，write mode 会拒绝：

agentmap init --write --targets CLAUDE.md,GEMINI.md

输出：

CLAUDE.md or GEMINI.md adapters require AGENTS.md to be targeted or already present.

agentmap init --profile minimal|standard

选择生成 profile。

standard 是默认值，包含 testing expectations、coding guidelines、planning、git safety 和 security sections。

minimal 只包含 scope、project context、setup、common commands、documentation、needs confirmation 和 adapters。

示例：

agentmap init --dry-run --profile minimal

输出：

AgentMap init dry-run

--- AGENTS.md ---
# AGENTS.md

## Scope
...

## Needs Confirmation
...

agentmap update --dry-run

预览对现有 AgentMap-managed blocks 的更新。这个命令不写文件。

示例：

agentmap update --dry-run

输出：

AgentMap update dry-run

--- AGENTS.md ---
# AGENTS.md

## Common Commands

<!-- agentmap:start commands -->
...

agentmap update --write

更新已存在的已知 managed blocks。Adapter files 会被验证并保留；AgentMap 在 update 期间不会重写手写 adapter 内容。

示例：

agentmap update --write

输出：

Updated AGENTS.md
Checked CLAUDE.md, GEMINI.md

如果 managed block 被人工编辑，update 会拒绝：

Managed block "setup" was manually edited; use --force-managed to rewrite it.

如果 target file 缺失，update 会拒绝并提示运行 agentmap init：

AGENTS.md is missing; use agentmap init to create target files.

agentmap update --write --force-managed

即使 bodyHash 显示 managed block 被人工编辑，也强制重写。

示例：

agentmap update --write --force-managed

输出：

Updated AGENTS.md
Checked CLAUDE.md, GEMINI.md

这个命令可能覆盖 managed block 内的人工编辑，使用前应先审查 diff。

agentmap check

验证生成文件，并打印人类可读结果。

示例：

agentmap check

输出：

AgentMap files are current and parseable.

带 warning 的输出：

AgentMap files are current and parseable.
warning AGENTS_OVERRIDE_SHADOWS_AGENTS: AGENTS.override.md exists and may shadow AGENTS.md.

agentmap check --ci

以 CI 模式执行相同检查。在 1.0.0 中，unresolved generated assumptions 默认是 warning，不会让 CI 失败。

示例：

agentmap check --ci

输出：

AgentMap files are current and parseable.

退出码：

0 = current and parseable
1 = stale, missing, or not initialized
2 = tool/runtime/configuration error
3 = malformed managed block or unsafe file state

agentmap check --json

输出 machine-readable diagnostics。

示例：

agentmap check --json

输出：

{
  "schema": 1,
  "status": "ok",
  "exitCode": 0,
  "files": [
    {
      "path": "AGENTS.md",
      "status": "ok",
      "managedBlocks": [
        {
          "block": "commands",
          "status": "ok"
        }
      ]
    }
  ],
  "warnings": [],
  "errors": []
}

可能出现的 warning 和 error codes：

MANAGED_BLOCK_STALE
MANAGED_BLOCK_MISSING
MANAGED_BLOCK_MANUALLY_EDITED
MANAGED_BLOCK_META_INVALID
MALFORMED_MANAGED_BLOCK
TARGET_FILE_MISSING
TARGET_FILE_UNSAFE
AGENTS_OVERRIDE_SHADOWS_AGENTS
GEMINI_DUPLICATE_CONTEXT
ADAPTER_IMPORT_MISSING
ADAPTER_CONTENT_DUPLICATED
OPTIONAL_MANAGED_BLOCK_MISSING
NEEDS_CONFIRMATION_UNRESOLVED
AGENTS_SIZE_WARNING
AGENTS_SIZE_STRONG_WARNING
CODEX_PROJECT_DOC_BUDGET_RISK

Size Budget

AGENTS.md 应保持紧凑。

target: <= 120 lines or <= 10 KiB
warning: > 16 KiB
strong warning: > 24 KiB
Codex-risk warning: near or above 32 KiB combined project instruction budget

当生成内容变大时，优先链接 repo-local docs，或由用户手动创建 nested instruction files，而不是膨胀 root file。

Optional Code Intelligence

GitNexus 等图谱工具只是可选 backend。AgentMap 默认不会安装它们、运行 graph indexing、写 MCP/editor config 或读取大型 graph databases。

High-confidence GitNexus detection 使用 repo-local signals，例如 .gitnexus/、.gitnexus/meta.json，或 repo-local agent files 中已有 GitNexus-managed instructions。

开发

运行测试：

npm test