Skip to content

ai_coding.md

Latest commit

 

History

History
163 lines (100 loc) · 11.8 KB

ai_coding.md

File metadata and controls

163 lines (100 loc) · 11.8 KB
Raw

AI 编码助手接入

本仓库支持多种 AI 编码助手（如 Claude Code、GitHub Copilot 等）协作开发。本文档说明如何把它们接入本项目，以及新增的 AI 协作约定应该放到哪一级。

核心原则：三级晋升

新增任何"给 AI 看的约定"时，按下面的阶梯从低到高放——能放低就不放高：

级别 位置 是否提交 适用
① 个人级 CLAUDE.local.md（及各工具的本地文件） ❌ gitignore 只对自己有用的偏好、实验性约定。先在这里试。
② 项目级 工具的项目文件（如 .claude/CLAUDE.md、.github/copilot-instructions.md）或 docs/develop/ 文档 ✅ 提交 团队共享、但某个工具特有的内容。
③ 统一源 根目录 AGENTS.md ✅ 提交 跨工具通用的项目知识（架构、硬约束、流程）。

晋升路径：① 个人级 →（证明对团队有用）→ ② 项目级 →（证明跨工具通用）→ ③ AGENTS.md。

  • 工具特有的内容（如 Claude 专属的 uv / context7 规则）不进 AGENTS.md，留在该工具的项目级文件里。
  • 只有"所有工具都该知道"的内容，才晋升到 AGENTS.md。

AGENTS.md：统一源

根目录 AGENTS.md 是跨工具的单一信息源（项目架构、开发硬约束、提交流程）；详细编码规范见 spec/agent_guidelines.md。

修改这两份即等同于更新所有已接入工具的行为——前提是内容确实跨工具通用。否则按上面的阶梯放低一级。

各工具接入

原则：入口文件优先放该工具自己的配置目录（如 .claude/、.github/），而不是项目根目录，避免根目录堆积。最理想的是工具能直接读 AGENTS.md——这样根本不需要入口文件。

Claude Code（用 @ 引用，不用硬链接）

  • 仓库已提交 .claude/CLAUDE.md，内部用 @../AGENTS.md 引入 AGENTS.md。Claude Code 启动时自动加载，无需配置。
  • Claude 特有的项目级规则写在 .claude/CLAUDE.md 里 @ 引入的下方（提交、团队共享）。例如强制 uv、用 context7、Bash 后台等。
  • 个人偏好写在仓库根 CLAUDE.local.md（gitignore），加载顺序在 CLAUDE.md 之后。

GitHub Copilot

  • 仓库已提交 .github/copilot-instructions.md（frontmatter applyTo: '**'，对所有文件生效）；每次会话自动注入，并 defer 到 AGENTS.md 取完整上下文。

其他工具（无原生引入机制时）

若某工具既读不了 AGENTS.md、又没有 @ 之类的引入语法，只能读它自己固定的入口文件，就用硬链接让该文件镜像 AGENTS.md。入口文件位置同样遵循上面的原则——优先配置目录，其次根目录。

示例（文件名依工具而定，此处以 CLAUDE.md 作占位演示命令形式）：

New-Item -ItemType HardLink -Path "CLAUDE.md" -Target "AGENTS.md"
  • 该入口文件应被 .gitignore 忽略，仅本地生效（个人级）。
  • 工具特有的项目级内容，另起一个提交的文件维护，不要塞进 AGENTS.md。
  • 将来某工具支持引入语法时，优先用引入、弃用硬链接。（Unix：ln AGENTS.md CLAUDE.md。）

内容该放哪（速查）

内容 放哪
只对自己有用的偏好 / 实验 ① 个人级：CLAUDE.local.md
团队共享、但某工具特有 ② 项目级：该工具文件（如 .claude/CLAUDE.md）
跨所有工具通用 ③ AGENTS.md

MCP

  • 推荐：context7 — 查询库文档；已在本项目 .claude/settings.json 启用（Claude Code 场景）。
  • 项目自有 MCP（感知/操作 tool 已实现）：把游戏感知/操作（窗口状态 / 截图 / OCR / 进游戏 + 运行态查/停）经 MCP 暴露给 agent，辅助开发与调试。传输 streamable-http（端点 /mcp，默认端口 23001）。先起服务（uv run --env-file .env python -m zzz_od.backend.entry.server），再 claude mcp add --transport http zzz_od http://127.0.0.1:23001/mcp。工具清单见 zzz/backend/mcp.md（不在此列举，避免随实现演进过时）；整体设计见 zzz/backend/，路线图见 harness/README.md。
  • 浏览器（chrome-devtools-mcp）：让 agent 经 CDP 驱动本机浏览器，读/操作 WebSearch 搜不到或抓不到的页面（米游社攻略、需登录活动页等）。connect 模式 + 调试 Edge，装法与会话坑见 chrome-devtools-mcp.md。

测试仓

测试代码在独立仓 zzz-od-test/(.gitignore,clone 到项目根目录),不在主仓。Claude Code 的 Grep/Glob 默认尊重 .gitignore,不会自动搜 zzz-od-test/——查/改测试须 Read/grep 显式指定 zzz-od-test/ 路径。clone 指引见 quickstart §②,规范见 spec/agent_guidelines.md。

LSP

项目用 uv 方式 pyright 做 LSP(代码导航:定义 / 引用 / 符号)——不用 Claude Code 官方的全局 pyright(走系统 PATH,解析不到项目 .venv 依赖,跟 uv 环境冲突)。pyright 在 dev 组、[tool.pyright] 配置(团队共享);Claude Code 的插件安装见 claude-code/pyright-lsp.md。

Skills

Skill 是 Claude Code（及 Codex 等少数工具）的可调用能力。要点：每个工具只读自己目录下的 skill——Claude Code 读 .claude/skills/，不读根目录 skills/；且 skill 没有 @import 之类的引入逃逸口。

推荐安装 superpowers

项目已统一采用 superpowers（团队共识）—— 它是一整套开发流程方法论，指导从需求探索（brainstorming）、写计划（writing-plans）、TDD 实现（test-driven-development）、调试（systematic-debugging）、code review、到分支收尾合并（finishing-a-development-branch）的全链路；本项目按这套流程开发。

本项目 dev skill（zzz-od-dev-*）是叠加在 superpowers 之上的项目特定补充（PR 收尾适配 CodeRabbit、本项目 skill 写作硬规范、修复决策框架等），非替代 —— 使用者需同时具备 superpowers。Claude Code 安装：插件市场搜 superpowers，或 /plugin install superpowers。

推荐安装 mcp-server-dev（写 MCP tool 时）

写本项目 backend MCP tool（src/zzz_od/backend/mcp/）时，通用 MCP tool 设计方法论遵循 Anthropic 官方 mcp-server-dev plugin（claude-plugins-official marketplace，专门 MCP 开发、3 个 skill 无杂烩）—— 尤其 build-mcp-server/references/tool-design.md（写好 tool：description 契约 / tight schema / annotations / 结构化返回 / actionable error / 读写分离 / token 经济）。本项目 mcp-implementation.md 只叠加项目特化（哪些 tool 标哪个 hint、MCP·HTTP 对称、screen_info CRUD、操作后 sleep 等），不重复通用知识。

Claude Code 安装（claude-plugins-official marketplace，两步）：

/plugin marketplace add anthropics/claude-plugins-official
/plugin install mcp-server-dev@claude-plugins-official   # 3 个 MCP skill(build-mcp-server/app/mcpb)，专门 MCP 无杂烩

Skill 分类与命名

Skill 分两类，统一用 zzz-od- 项目前缀，开发类再加 dev-：

类别 前缀 用途
开发 zzz-od-dev- 指引 AI 在本项目开发/配置/构建（superpowers 风格）
历史遗留 无前缀 早期 skill，暂保留原名（迁移价值待评估）

现有 skill 清单见 skills/ 目录（每个 SKILL.md frontmatter 有触发描述），不在此罗列以免随增减过时。

zzz-od- 兼作项目命名空间——避免和插件/个人 skill 撞名，/ 列表里本项目 skill 聚一起。命名示例：zzz-od-dev-character（新增角色）、zzz-od-dev-build（构建配置）、zzz-od-player（安装使用）。将来若出现第 3 类（如调试），加对应中缀（zzz-od-debug-*）即可。

Skill 开发：三级晋升

跟整体"三级晋升"一致，新增 skill 从低到高放：

级别 位置 是否提交 说明
① 个人级 .claude/skills/<name>/（.claude/* 已 gitignore，天然不提交）或 ~/.claude/skills/ ❌ 先在这里试做、验证有用再升级。
② 工具项目级 .claude/skills/<name>/（提交：.gitignore 放行 .claude/skills/） ✅ 团队共享、Claude Code 特有。
③ 项目级（跨工具源） 根目录 skills/<name>/（提交） ✅ 多个"skills 感知"工具都要用时，作单一源。

晋升路径：① 个人试做 →（验证有用）→ ② 提交到 .claude/skills/ →（多工具都要）→ ③ 根 skills/ 作跨工具源。

⚠️ 根 skills/ 不会被工具自动发现，只是③的单一源；要目录联接（junction，mklink /J，目录级）进各工具目录（如 .claude/skills/）。Windows junction 免管理员（symlink 需特权/开发者模式）。只有 Claude Code 一个消费者时，停在②即可，不必上③。

现状

仓库根 skills/ 是 skill 的单一源（③）；开发类（zzz-od-dev-*，superpowers 风格）经 junction（.claude/skills/<name> → 根 skills/<name>）被 Claude Code 自动加载。现有 skill 清单见目录本身（每个 SKILL.md frontmatter 有触发描述），不在此罗列以免随增减过时。

新 skill 按上面的命名规范用 zzz-od- 前缀。

AI 辅助提交的署名（推荐）

用 AI 编码工具协作时，推荐在 commit 消息里用 Co-Authored-By trailer 标明 AI 参与——让提交历史能看出哪些是 AI 协作的（透明、可追溯），GitHub 会识别该格式并把 co-author 显示在提交上。

Co-Authored-By: <名字> <邮箱>

落地有两种做法，按“靠模型自觉 → 全自动”递进：

做法一：在指令文件里写指引

在该 AI 工具的指令文件里写一条，让它自己加 trailer（例如“提交时在 message 末尾追加 Co-Authored-By: <工具> (<模型>) <邮箱>”）。

  • ✅ 零配置、跨工具。
  • ❌ 靠模型自觉：会忘、会漏，模型名也可能写错。

做法二：用 git hook 自动注入（推荐）

用 git 的 prepare-commit-msg 钩子在每次提交时自动追加 trailer，不依赖模型记忆。git 每次提交都会调它，链式 &&、git -C <dir>、--amend 全覆盖。两种粒度：

  • 2a. 钩子里写死内容（静态）：硬编码固定 trailer。最简单、稳；但不反映实际模型。
  • 2b. git hook + AI 工具 hook 写入模型名（动态）：git 钩子注入 trailer；再用 AI 工具自带的 hook 在每次 git commit 前把当前模型名写到侧信道文件，git 钩子读取 → trailer 反映实际模型，模型一换跟着变。需把工具默认的 co-author 指令关掉，避免重复。

各工具的具体实现不同——Claude Code 的做法见 Claude Code：自动注入 commit trailer；其他工具用各自等价的 hook 机制。

注：部分工具/模型厂商没有官方 GitHub bot 邮箱，模型那行的邮箱只是占位（GitHub 上不出头像/contributor）；推荐用对应厂商官网域名（如 noreply@<官网域名>）作占位。

相关文档