跳到正文
heng-agent v0.5.0
Esc
使用指南目录

进阶

兼容 Claude Code 与 AGENTS.md

从 Claude Code 转过来不用迁移：CLAUDE.md、AGENTS.md、.claude 里的技能、子智能体、自定义命令、权限规则、钩子，以及 .mcp.json 都直接读；哪些照搬、哪些不跟，怎么关掉用户级的读取。

预计用时
约 5 分钟
适用版本
v0.5.0 及以上

现成的配置直接能用

项目里、用户目录里给 Claude Code 写的配置，heng-agent 都读：

配置 读哪里 说明
项目说明 根目录的 HENG.md、AGENTS.md、CLAUDE.md、CLAUDE.local.md；子目录里的同名文件 都读；内容一样的只算一份；CLAUDE.md 的 @路径 引用会展开
用户说明 ~/.heng-agent/HENG.md、~/.claude/CLAUDE.md
技能 .claude/skills/、~/.claude/skills/ 格式一样；同名时 .heng-agent/ 的优先
子智能体 .claude/agents/、~/.claude/agents/ Claude 的工具名（Read、Bash……）自动对应；不写 tools 时照 Claude 的规则继承全部工具
MCP 项目根目录的 .mcp.json 支持 ${变量}、${变量:-默认值}；项目里的服务照样要确认信任才启动
自定义命令 .claude/commands/（可分子目录）、~/.claude/commands/ 支持 $ARGUMENTS、$1…$9、argument-hint、!`命令`（先跑命令把输出拼进去：用户级的直接跑，项目里的先问你，脚本模式只在全部放行时跑）
权限规则 ~/.claude/settings.json；项目 .claude/settings.json、settings.local.json 规则自动翻译（Bash(npm test:*) → bash(npm test*) 等）；项目里的只采用拒绝规则
钩子 同上几个 settings.json 的 hooks 支持 PreToolUse、PostToolUse、UserPromptSubmit、Stop、SessionStart，照 Claude 的约定传 JSON、认退出码 2；项目里的要确认信任

欢迎页会显示「兼容加载：……」，/doctor 也列出来。

哪些不跟

  • 权限模式：.claude/settings.json 里的 defaultMode 不跟，权限模式由 heng-agent 自己定；
  • 项目里的允许规则：只采用拒绝规则，别人的仓库没法给自己放开命令；
  • 登录方式：不支持 Claude 订阅账号登录（OAuth），用 Claude 请用 API 密钥或中转站，见 服务商与配置文件。

拒绝规则对组合命令逐段检查（cd x && 危险命令 也拦得住），文件路径换写法（./.env、E:\项目\.env）也拦得住。

几份说明并存时

系统提示词里按优先级从低到高排列，并告诉模型「内容冲突时以后面的为准」：用户级在前、项目级在后；同一级里 CLAUDE.md < AGENTS.md < CLAUDE.local.md < HENG.md；子目录的说明比根目录的更具体。读到写给 Claude Code 的说明时，还会附一段工具名对照（Bash → bash、Edit → edit_file……）。

/memory 按这个顺序列出每份说明各占多少 token，详见 项目记忆。/init 默认生成 AGENTS.md（跨工具的开放标准），项目里已有说明文件就更新现有的。

不想读 ~/.claude

  • 不读 Claude Code 的用户级配置（~/.claude 里的）：/config set settings.claude_user_config false，项目里的照读；
  • 有些 Claude 钩子是专给 Claude Code 自己用的集成，在 heng-agent 里跑会出错或记错：写进 settings.claude_hooks_skip，命令里含其中任一段文字的 Claude 钩子不跑。
{ "settings": { "claude_hooks_skip": ["aicoder-claude-session-recorder"] } }

做完是这样

在一个用过 Claude Code 的项目里启动，欢迎页的「兼容加载」一行列出读到的说明、技能、命令和规则；/memory 里能看到 CLAUDE.md，/skills、/agents 里能看到 .claude/ 下的技能和角色。

最后更新：