软件技术分享

关于电子游戏的方方面面

三工具对照：写技术说明文档谁更稳

作者

写内部 README／操作手册：按锚点来源选 Grok／Claude／Codex，无永远冠军；一次生成≠可维护文档。

要点

  • 事实锚点：Codex／Cursor 能直接读仓库文件再写（高，Codex CLI）；Claude Projects 可把规范放进知识库反复改（高，Projects Help）；Grok 适合带网页／𝕏 citations 的外部产品变更说明（高，Grok 产品页）。内部私有仓对 Grok 实时检索＝弱。
  • 结构稳定：三家都能按提示出目录与步骤；稳定性更取决于你是否写死“完成定义”（读者、必含节、禁止编造 API）。证据：编译可跟做（中高）；非官方 SLA。
  • 改仓贴合：Codex／Cursor 对着代码写文档是优势；风险是“写飘”：文档写成与代码不一致的愿望清单。须先读再写、diff 必审（中高，衔接本室《先读再改》《完成定义》）。
  • 检索时效：外部 SaaS／公开 changelog 用 Grok Search／多代理更合适；闭源内部手册别指望网页检索补全。证据：高／边界清晰。
  • 长文与项目知识：Claude Projects＋Artifacts／Docs 适合粘贴规范后多轮打磨同一份说明。证据：高（Projects；Artifacts）。
  • 选型克制：API 贴仓手册偏 Codex；规范长文迭代偏 Claude；公开产品变更速记偏 Grok。可混用：Codex 抽代码事实 → Claude 调结构 → Grok 核外部链接。
  • 证据强度总表见正文对照表；任何“某家全面碾压”断言＝低，本稿不采用。

正文

场景

你要给同事交一份内部技术说明：怎么在本仓库跑集成测试、环境变量从哪来、出了 503 先查哪三处。材料散落在 README 残骸、两段 Slack、以及真实代码。分别丢给 Grok、Claude、Cursor 里的 Codex，常出现三种失败：漂亮目录但对不上函数名；结构整齐但 API 是编的；贴着仓库写却把“计划中的重构”写进现行步骤。

下面用同一任务、同一提示骨架、同一完成定义对照五条评价轴。结论先说清楚：没有永远冠军；按文档类型选型；一次生成能交差，量产可维护还要版本与人工终核。

可跟做步骤／可抄工作流

证据强度：产品能力句＝高（三家官方页／Help）；“谁更稳”的相对排序＝中（场景编译，非榜单测评）。

1. 统一任务与完成定义（三家共用）

在开任何工具前写好合同，粘进提示顶部：

【文档任务】给同事用的内部技术说明（README／操作手册草稿）
【读者】本团队后端／支持，已有仓库读权限；非对外营销稿
【必含节】
1. 目的与适用范围（含“不覆盖什么”）
2. 前置条件（账号、目录、依赖版本，且只写材料里有的）
3. 分步操作（编号步骤；每步可验证的预期结果）
4. 常见失败与排查（只列已知）
5. 相关文件路径／命令（必须能在仓库或我粘贴材料中找到）
6. 未知与待确认（单独一节，禁止删掉）
【禁止】
- 编造不存在的 API、旗标、环境变量、端口、文件路径
- 把“建议重构”写成现行步骤
- 无来源的版本号与耗时承诺
【完成定义】
- 每一处命令／路径／API 都能指回：仓库文件 或 我粘贴的原文 或 可打开的检索引用
- 指不回的必须进“未知与待确认”
- 输出 Markdown；先给目录再给正文

2. 五轴对照（写说明文档场景）

评价轴GrokClaudeCodex／Cursor 改仓证据强度
1 事实锚点强在网页／𝕏 实时引用；弱在进不了你的私有仓强在你粘贴／上传的材料与项目知识库；可要求先摘录再写强在直接读本地仓库再写文档高（产品能力）／相对排序中
2 结构稳定提示写清时目录可用；易顺手扩成“行业综述”Artifacts／Docs 便于盯着同一份长文改结构易按仓内已有 README 风格续写；也可能步骤编号被重构叙述打散中高（完成定义依赖）
3 改仓贴合不贴仓；适合外链说明不直接改仓；适合规范层优势最大；“写飘”风险也最大（文档超前于代码）高／风险中高
4 检索时效外部产品变更说明首选之一开 Web search 时可补公开页；默认偏你提供的材料CLI 可 --search 补公开文档；默认主场仍是本地仓高
5 长文与项目知识Canvas／长对话可改，缺“项目知识库”式跨聊资产时要自备粘贴Projects 知识库＋指令＋Artifacts 适合反复打磨同一手册文档文件可直接落在仓内并走 PR；跨主题规范仍建议另备 CLAUDE／AGENTS 规则高

读表方式：选工具看你的证据从哪来。证据在公开网上 → 偏 Grok；证据在一叠规范 PDF／旧手册 → 偏 Claude Project；证据在当前 commit 的代码 → 偏 Codex／Cursor。

3. 三家怎么开跑（可跟做）

A. Grok（外部变更／公开产品说明向）

  1. 打开 grok.com／App，选用当前界面的检索／Search（或多代理，名称以界面为准）。
  2. 粘贴完成定义＋“只依据检索可打开来源与我粘贴原文”。
  3. 要求文末列出实际引用链接；打不开的删。
  4. 内部私有步骤若材料不足，应进“未知”，不要用训练记忆补命令。

衔接：本室《Grok 检索少幻觉》《竞品公开情报检索流程》。核链纪律同样适用于技术说明里的外链。

B. Claude（规范长文／多轮结构向）

  1. 建或打开 Project；把已定稿规范、术语表、旧手册脱敏版放入知识库（勿放密钥）。
  2. 项目指令写入完成定义中的禁止项。
  3. 新开聊天：“先列出材料中的逐字摘录与路径，再写手册；写进 Artifacts／Docs 便于改。”
  4. 每轮只改一节；要求更新“未知与待确认”。

衔接：《建第一个 Project》《长文档超限与项目知识库》《Artifacts 边界》《幻觉校验清单》。

C. Codex／Cursor（贴仓 README／操作步骤向）

  1. 在仓库根目录开 Codex CLI 或 Cursor Agent；权限用可读可写工作区、危险命令仍审批（见官方 approvals）。
  2. 先读再写：点名 README*、实际入口脚本、配置样例；禁止未读文件就写步骤。
  3. 提示示例：
先只读：列出与“本地跑集成测试”相关的文件路径与关键命令（附文件路径）。
确认后：更新／新建 docs/ops-integration-tests.md，遵守上方完成定义。
不得修改业务代码；文档中的命令必须能在当前仓库复现或标未知。
  1. 看 diff：路径是否真实、步骤是否把 WIP 写成现行、有无编造 flag。
  2. 可选 codex --search 仅用于核对公开上游文档版本；私有约定仍以仓内为准。

衔接：《Cursor／Codex 先读再改》《Codex 多文件重构完成定义》《终端命令审批》。

4. 推荐混用流水线（量产向）

  1. Codex 输出“代码事实表”（路径｜命令｜摘录｜置信）。
  2. Claude 按完成定义排版成手册，未知节留空位。
  3. 若含第三方 SaaS／公开 API 变更，Grok 补一节外链并核链。
  4. 人工终核：抽 3 条命令实跑或对照 CI；链接全开。
  5. 合入仓库的文档走 PR，避免聊天里“最新版”与仓内漂移。

演示一次生成可以过会；可维护要有：完成定义模板、事实表、PR、未知节不清空。

真实用户诀窍／反例

  • 诀窍：先选证据源，再选模型。 工具争论常是证据源没对齐。
  • 诀窍：完成定义里的“未知节”不可删。 删掉等于鼓励编造。
  • 诀窍：贴仓写作必须 diff 审“愿望清单”。 文档超前代码是常见事故。
  • 诀窍：外部说明与内部手册拆文件。 时效策略不同，硬揉一份必过期。
  • 反例：三家各生成一版后用“最长最全”当胜者。 最长往往掺水与幻觉。
  • 反例：对 Grok 说“根据我们仓库”。 它看不见私有仓，除非你粘贴。
  • 反例：Claude 知识库塞全仓 zip 当唯一真相。 易过期；贴仓真相仍在 git。
  • 反例：Codex 边写文档边“顺手重构”。 完成定义应禁止改业务代码（除非另开任务）。

适用边界

  • 本稿是内部技术说明／README／操作手册场景的工具选型对照，不是编程能力总榜，也不是延迟／价格评测。
  • 产品功能名、按钮文案、套餐可用性随版本变，以各产品页与你的界面为准。
  • 不覆盖合规审计正式文档、对外法律文本；那些还要法务模板。
  • “更稳”指更少无锚点编造与更少结构跑偏的工作流倾向，不是正确率百分比承诺。

【来源与编译】