项目规则与导入

概念

项目规则是 Matcha CLI 在对话开头注入的 Markdown 指令文件。为 Matcha CLI 应写的是仓库根目录的 AGENTS.md（需要时也可放在子目录）。

在对应兼容开关打开时（默认打开），Matcha CLI 也会发现其他工具用的同一类文件——CLAUDE.md、.claude/rules/、.cursor/rules/，以及它们在主目录下的对应文件。

导入是另一回事。/import-claude 把设置（权限、环境变量、MCP 服务器、钩子，以及额外的技能/规则路径）从 ~/.claude 复制进 Matcha CLI 配置。它不会替换 AGENTS.md。规则文件就地读取；设置在你确认对话框后才复制。

matcha inspect 会列出它找到的每个规则文件、技能和 MCP 服务器，并标上来源。

为何重要

每回合重复「用 pnpm」「不要改 generated/」「这个包用 CSS modules」，既浪费上下文又会走样。一份短的 AGENTS.md 是最有用的定制。

若已有 Claude 或 Cursor 的材料，不必重打一遍。发现负责 Markdown。/import-claude 负责 JSON 设置。用 matcha inspect 核对两者。

Matcha CLI 会自动读什么

具名指令文件

在扫描的每个目录里，Matcha CLI 按此顺序查找这些名字，并加载找到的每一个不同文件：

• Agents.md
• Claude.md
• CLAUDE.md
• CLAUDE.local.md
• AGENT.md
• AGENTS.md

在不区分大小写的磁盘上，Agents.md 和 AGENTS.md 是同一文件，只计一次。

Claude 兼容打开时（默认），它还会在 ~/.claude/ 查找这些名字，并在每一级项目目录读取 .claude/CLAUDE.md 和 .claude/CLAUDE.local.md。Cursor 兼容对 ~/.cursor/ 做同样的事。

规则目录

这些文件夹里的每个 *.md 文件都会加载（任意文件名）：

先加载主目录规则（Matcha CLI，然后 Claude，然后 Cursor），再从 git 根目录往下到当前目录加载项目文件。规则文件夹内按字母序。更深层的具名文件排在后面，指令冲突时以后者为准。

不在 git 仓库里时，只扫描当前目录（外加主目录）。

被 .gitignore 忽略的文件会跳过。个人覆盖放进已识别的名字，例如 CLAUDE.local.md，并把该名字加入 gitignore。像 AGENTS.local.md 这样的自定义名在顶层不会被发现——只在 rules/ 目录内才会。

`AGENTS.md` 里写什么

可执行的指令，不要复制 README：

# My Project
- Run tests with `pnpm test`
- Never edit files under generated/

构建命令、约定和易踩的坑写在这里。团队共用规则放进仓库。个人默认放在 ~/.matcha/AGENTS.md 或 ~/.matcha/rules/。

只对这一次会话生效、又不改文件时：

matcha --rules "Always use TypeScript. Prefer functional components."

从 Claude、Cursor 或 Codex 过来

不需要 /import-claude 就会拾起（对应兼容单元打开时）：

• 规则 — AGENTS.md、CLAUDE.md（含嵌套）、.claude/rules/、.cursor/rules/，以及主目录下的对应文件。
• 技能与自定义命令 — ~/.claude/skills/、~/.claude/commands/、~/.cursor/skills/，以及项目级副本。扁平的命令 .md 文件会变成斜杠命令。
• MCP 服务器 — ~/.claude.json、.cursor/mcp.json、项目 .mcp.json。
• 钩子 — .claude/settings.json，包括 Bash 这类 matcher 别名。

每一面都是 ~/.matcha/config.toml 里的一个单元。默认打开。环境变量优先于文件；文件优先于默认值。

[compat.claude]
skills = true
rules = true
agents = true
mcps = true
hooks = true

[compat.cursor]
skills = true
rules = true
agents = true
mcps = true
hooks = true

rules 和 agents 彼此独立。Codex 的 skills / rules / agents / mcps / hooks 单元已预留，目前无作用。

导入 Claude 设置

/import-claude 打开一个复选框对话框。欢迎屏上用 Ctrl+I（或在导入那一行按 i）也会打开同一对话框。

它会扫描：

• ~/.claude/settings*.json 和项目 .claude/settings*.json（权限、环境变量、钩子）
• ~/.claude.json（MCP 服务器）
• 项目 .mcp.json
• ~/.claude/{skills,rules} 和 <repo>/.claude/{skills,rules}（作为额外搜索路径）

列表按 Global 与 Project 分组，再按 Permissions、Env vars、MCP servers、Hooks 和 Paths。可切换一行、一组或整个范围。确认后只写入勾选的项。

写入是追加的：

• 全局项 → ~/.matcha/config.toml（钩子还会写入 ~/.matcha/hooks/imported-from-claude.json）
• 项目项 → <repo>/.matcha/config.toml（以及那里的 .matcha/hooks/imported-from-claude.json）

已有的键和 MCP 服务器名不会被覆盖。随时可再跑这条命令；跳过的项仍可选用。

关掉欢迎行会记下你已拒绝。此后 Matcha CLI 不再在运行时静默读取那些回退路径上的 .claude/ 设置。AGENTS.md / CLAUDE.md 的发现不受影响。改主意后再跑 /import-claude。

核对发现了什么

在项目目录下：

matcha inspect
matcha inspect --json

人类可读输出包括：

• Project Instructions — 路径、范围（project / user / …）、大约 token 数，以及来源标签（文件来自该树时会标 [claude] 或 [cursor]）。已关闭的兼容面仍会列出并做标记。
• Skills、MCP Servers、Hooks — 每项带有来源标签，以及同样的来源 / 已关闭标记。丢掉裸名的技能会显示 [collides with /login → /acme:login]。
• 本地运行层兼容性 — 每个单元显示 on 或 OFF，并带 (default)、(config) 或 (env)。

inspect 会在所有厂商面都打开的情况下走磁盘，因此能看到会话开始时兼容开关会藏起的文件。若文件夹未受信任，仓库内的钩子、插件和 MCP/LSP 条目会标为已门控；inspect 不会启动那些服务器。