autocode 使用指南

概述

autocode 把工单项目的业务规则写成一个可查询的知识库 .autocode/，让 Claude Code / Codex 在写代码前先读懂"为什么、给谁用、有什么规则"，而不是通读源码去猜。代码回答"怎么做"，知识库回答"为什么"。

它对开发的三个直接收益：

• 需求把握更准 ：/auto-feat、/auto-fix 把原始需求或缺陷用本项目的业务术语重述，并点名涉及的业务单元、代码位置与锚点，再出实现计划；拿不准的地方会变成待答问题，而不是被 AI 悄悄猜掉。
• 上下文自动注入：每次提问时 hook 自动把相关业务术语、领域文档塞进上下文，AI 不用你提醒就知道"自动建单""转人工""场景版本"分别指什么。
• 定位更快 ：autocode query 按锚点或业务说法找文档，autocode graph 直接给出调用链，省掉大量 grep。

知识库目录（.autocode/ 已随父仓库入库）：

路径	内容	谁维护
project.md	项目一句话、核心流程、模块划分	项目负责人手写，优先级高于代码推断
glossary.md	业务术语表；首列状态为"已确认"的是拍板口径	引擎生成，人确认
domains/	领域文档，一个业务模块一篇（当前 18 个领域）	引擎生成
units/	单元文档，一个业务能力一篇，带代码锚点	引擎生成
entries.md	全部入口（路由、页面、消费者、定时任务）及所属单元	引擎生成
questions/	待答问题，一个问题一个文件	引擎提问，人在"回答"段作答
feat/、fix/	需求与缺陷文档：原文、整合重述、实现计划	/auto-feat、/auto-fix 生成，人确认
config.yaml	开发阈值、预算、并发等配置	人

state.db（对话采集）与 .autocode-graph/（代码图）是本地派生数据，已被 .gitignore 排除，每人本地生成。

快速开始

新人按下面 5 步接入，约 10 分钟。前提：Node.js ≥ 22.5（autocode 用内置 node:sqlite），并已安装且登录 Claude Code 或 Codex CLI------autocode 调用的是你本机的 claude -p / codex exec，不需要单独的 API Key。

1. 全局安装 autocode：

npm install -g @ethan.carter/autocode
autocode --version

2. 在仓库根目录运行 autocode init：知识库文档已入库，这一步只生成本地代码图、引用索引并探测可用模型，不调 AI、不改文档。 3. 安装宿主集成（仓库里已带 Claude Code 一套，版本过期时 autocode check 会报 host-outdated）：

autocode install claude   # Claude Code：斜杠命令、skill、CLAUDE.md 标记块、hook
autocode install codex    # Codex：AGENTS.md 标记块、.codex/hooks.json、~/.codex/prompts/auto-*.md
autocode install all      # 两边都用时

4. 体检一次：autocode check，确认没有失效锚点和宿主文件过期。

接入后在仓库根目录启动 Claude Code 或 Codex，随便问一句业务问题（如"转人工待办怎么生成"），能看到 AI 引用 .autocode/ 里的文档就说明接通了。

命令速查

日常最常用的是 /auto-feat、/auto-fix 和 autocode query；其余命令按需使用。所有命令都可加 --json 输出机读结果。

命令	Claude Code 斜杠命令	做什么	调 AI
autocode feat "``自然语言``"	/auto-feat	用本项目业务术语重述需求，出实现计划	是
autocode fix "自然语言"	/auto-fix	重述缺陷、定位根因，出修复计划	是
autocode query <锚点或关键词>	---（skill 自动用）	查文档、业务术语释义、入口、相关需求	否
autocode graph <锚点>	---（skill 自动用）	查调用链：谁调用它、它调用谁	否
autocode wiki ["自然语言"]	/auto-wiki	按代码变更和已答问题增量更新知识库	是
autocode check	/auto-check	体检：失效锚点、待确认术语、未达开发阈值等	否
autocode init	/auto-init	初始化或刷新骨架、代码图、宿主集成	否
`autocode install [claude	codex	all]`	---	安装或刷新宿主文件	否

feat / fix 的常用参数：

• --attachments <仓库内文件夹>：截图、PDF、接口文档等参考材料，引擎复制进变更文件夹。
• --no-plan：只出重述不出计划；定稿后用 --plan-only <文档id> 补计划。
• 带上文档 id 重跑就是改版，生成新版本。

wiki 的常用写法：不带参数 = 增量；autocode wiki "只更新自动建单" = 按指令更新；--scope unit:<文件名>,domain:<领域id> = 只重写指定几篇。"全部重写"费用高，运行前先和项目负责人确认。同一时间只能有一个 wiki / init 在跑。

日常工作流

核心原则：需求先在知识库里对齐口径，整合文档确认、且涉及的文档达到开发阈值（默认 0.8）后才动代码。

审阅不通过就带文档 id 重跑出新版本；未达阈值时先补知识库，不要硬写代码。

需求开发：/auto-feat

1. 取原文：直接粘贴 PRD，或给 URL、飞书项目工作项、仓库内文件路径；飞书文档链接由 lark skill 取正文。截图、接口文档放进仓库里的临时文件夹，用 --attachments 交给引擎。
2. 运行 /auto-feat <一句话说明>，引擎在 .autocode/feat/feat-<日期>-<序号>-<标题>/ 下生成：original.prd.md（原文）、integrate.prd.md（整合重述）、prd.plan.md 及子计划 prd.plan.01-*.md...
3. 审阅：重点看重述是否用对了业务术语、涉及的业务单元和代码位置是否齐全、"未决问题"一节怎么答。要改就直接编辑文件，或 /auto-feat <文档id> <修改意见> 出新版本。
4. 确认：把整合文档与每份计划 frontmatter 的 confirmation 改为 confirmed（未确认的文档不会被知识库读取）。
5. 实现：输出"后续"里的开发阈值达标时，AI 会问是否按计划实现；每完成一步会报改了哪些文件，要动计划外的模块时先停下来问你。
6. 代码合并后运行 /auto-wiki，让知识库跟上代码。

缺陷修复：/auto-fix

流程与 /auto-feat 相同，原文换成报错日志、缺陷单或复现步骤；引擎会额外定位根因，文档落在 .autocode/fix/。

编码前先查

不走 feat / fix 的小改动，也先让 AI 查一遍：

autocode query 自动建单 --json            # 按业务说法找文档与术语
autocode query CreateWorkOrder --json       # 按锚点找所属单元和规则
autocode graph CreateWorkOrder --json       # 看谁调用它、它调用谁

Claude Code 下无需手动敲：autocode-query / autocode-graph 两个 skill 会引导 AI 自己调用。

回答待答问题

引擎拿不准的地方会先按推断写进文档，并在 .autocode/questions/ 留一个问题文件。当前有 250 多个待答问题，其中 7 个是 blocking，会拉低开发阈值。

1. 在问题文件的 ## 回答 段写答案，frontmatter 改 status: answered。
2. 运行 /auto-wiki（不带参数），依赖这个答案的文档在这一趟更新。

也可以直接跑 /auto-wiki，AI 会把优先问题逐条问你，并把回答逐字写回。

更新知识库

• 合并了业务代码、答了问题、确认了术语之后，跑一次 /auto-wiki 增量更新。
• 业务事实可以直接写进指令，如 /auto-wiki 转人工待办多人先到先得，引擎会把原话记为人工确认的答案。
• 定期跑 /auto-check（不调 AI），及早发现失效锚点和过期的宿主文件。

Claude Code 与 Codex 下的使用

两边读的是同一份 .autocode/ 知识库，差别只在入口：Claude Code 有完整的斜杠命令和 skill，Codex 以直接调 CLI 为主。

能力	Claude Code	Codex
项目指令	CLAUDE.md 里的 autocode 标记块	AGENTS.md 里的 autocode 标记块
斜杠命令	/auto-feat、/auto-fix、/auto-wiki、/auto-check、/auto-init（.claude/commands/）	autocode install codex 写入 ~/.codex/prompts/auto-*.md 自定义提示词；也可直接让 Codex 跑 CLI
查询 skill	autocode / autocode-query / autocode-graph，AI 自动在编码前查	无 skill，靠 AGENTS.md 提示或你在提问里点名 autocode query
上下文注入 hook	.claude/settings.json：提问时 autocode inject，结束时 autocode capture	.codex/hooks.json 同样结构，目前为实验性支持

Claude Code 示例

/auto-feat 中台建单抽屉支持先输订单号反查店铺，原文如下：<粘贴 PRD>
/auto-feat 使用飞书skill，查看新的需求内容，网页链接：https://freecallai.feishu.cn/wiki/RaOOwYJR2igtTjksySvcQfyknPd
/auto-fix 自动建单延迟队列到期未建单，日志如下：<粘贴日志>
/auto-fix 使用飞书skill，查看新的bug内容，网页链接：https://freecallai.feishu.cn/wiki/RaOOwYJR2igtTjksySvcQfyknPd
/auto-wiki

普通开发任务直接用自然语言提问，hook 会自动注入相关术语和文档，skill 会让 AI 先 autocode query 再读代码。

Codex 示例

在 Codex 里让它直接执行 CLI，原文一律走 stdin：

autocode feat "中台建单抽屉先输订单号" <<'AUTOCODE_ORIGINAL'
<需求原文，逐字粘贴>
AUTOCODE_ORIGINAL

autocode query 转人工 --json
autocode wiki

建议在给 Codex 的任务里加一句"动手前先用 autocode query 查相关文档"，弥补没有 skill 的差距。feat / fix 耗时较长，允许的命令超时应不少于 10 分钟，wiki 不少于 30 分钟。

规则与常见问题

知识库的准确度靠"引擎生成、人拍板"维持，以下纪律请所有开发遵守。

纪律

• 业务术语逐字复用 ：提需求、写代码注释、跟 AI 对话时，用 glossary.md 里的名字，不另造同义词；状态为"已确认"的口径以它为准。
• 不手改引擎生成的文档 ：domains/、units/、entries.md 由 /auto-wiki 维护。人可以直接动的只有：问题文件的"回答"段、术语表首列"状态"、project.md、config.yaml、需求 / 缺陷文档及其 confirmation 字段。
• 改代码不回写需求文档 ：需求 / 缺陷文档是当时的意图记录，和最终代码有出入是正常的；下次 /auto-wiki 会把出入变成问题交给人裁决。
• 不替别人答问题：拿不准就选"稍后再答"，错误的答案比待答问题危害更大。
• 提交 ：.autocode/ 和 .claude/ 的改动提交到父仓库（git@gitee.com:chengduzhihuige/workorderspace.git，master 分支）；子模块里的业务代码先在子仓库提交推送，再回父仓库 git add app/<name> 提交指针。.autocode/state.db、.autocode-graph/ 不入库。

常见问题

现象	处理
autocode: command not found	未全局安装，执行 npm install -g @ethan.carter/autocode；并确认 Node.js ≥ 22.5
报"未初始化"	在父仓库根目录运行 autocode init
报"无可用 provider"	本机没有登录的 Claude Code / Codex CLI，安装并登录其一
报"另一个 ... 正在运行"	wiki / init 同时只能跑一个，等它结束再试，不要删代码图
autocode check 报 host-outdated	运行 autocode install 刷新宿主文件
/auto-feat 提示未达开发阈值	按"先处理"列表回答 blocking 问题、确认术语，再跑 /auto-wiki
飞书文档链接取不到原文	网页抓取拿不到飞书正文，需配好 lark-cli 或飞书 MCP，或直接粘贴正文
从 Gitee SSH 拉取报 Permission denied (publickey)	该 key 没加到 Gitee 账号；可用 git config core.sshCommand "ssh -i <你的 key> -o IdentitiesOnly=yes" 为本仓库单独指定，或改用 HTTPS