真实项目贯穿实战

这一篇把前面的概念串成一个真实项目流程。目标不是展示炫技，而是形成一套可重复、可验证、低干扰的 Gemini CLI 工作方式。

场景

假设你要给一个文档站补一个新产品栏目。仓库里还有其他 agent 在改别的栏目，所以你必须互不干扰。

第一步：只读进入项目

先进入项目目录，再运行 gemini。

第一条 prompt：

请只读扫描当前项目，不要修改文件，不要执行写入命令。请说明项目技术栈、文档目录、导航机制、验证命令，以及我应该只改哪些路径。

输出里必须能看到：

• 项目技术栈。
• 内容目录。
• 导航文件。
• 检查命令。
• 不应触碰的并发改动区域。

第二步：确认上下文真相源

让 Gemini CLI 查：

请读取当前目录和父目录的规则文件，确认本次任务应遵守哪些 CLAUDE.md、AGENTS.md 或 GEMINI.md 规则。

如果项目还没有 GEMINI.md，可以先生成一个小范围项目规则草案，但不要把它写入仓库，除非团队确认。

第三步：写计划，不直接改

我要新增 Gemini CLI 教程栏目。请先给执行计划：目录结构、页面清单、官方来源、每批修改文件、验证方式和停止条件。不要改文件。

计划里应该明确：

计划里要明确只改 content/docs/gemini-cli/，不碰其他产品栏目；每批前检查 git status，每批后跑 types:check 或至少跑 MDX 检查。

第四步：分批写入

按批次推进：

1. 创建根页面和导航。
2. 写官方教程中文版。
3. 写从原理到实战。
4. 补美化组件和交叉链接。
5. 跑验证。

每批之间都检查：

git status --short content/docs/gemini-cli

如果发现别人也改了 content/docs/gemini-cli/，暂停合并，不要覆盖。

并发协作表

第五步：验证

先做目标目录检查：

rg -n "[[:blank:]]+$" content/docs/gemini-cli

再跑项目检查：

建议按顺序跑 pnpm run types:check、pnpm run audit:content、pnpm run audit:quality、pnpm run build。

如果失败，先判断是不是本次目录引起。并发仓库里不要顺手修别人改动造成的问题。

第六步：自动化沉淀

当这套流程跑通后，再考虑：

• 用 headless mode 定期对比官方 docs 变更。
• 用 GitHub Action 给 PR 自动检查文档导航。
• 用 Skill 固化“教程栏目新增流程”。
• 用 hooks 阻止跨栏目误改。

完整工作流

官方来源采集
  -> 内容蓝图
  -> 根页面和导航
  -> 官方教程中文版
  -> 从原理到实战
  -> 美化和交叉链接
  -> 类型检查和构建
  -> 发布前复检

结束标准

一个真实项目任务不是“文件写完”就结束。结束标准应该是：

• 页面能被导航发现。
• 链接不指向不存在的 slug。
• 类型检查通过。
• 构建通过。
• 并发改动未被覆盖。
• 官方来源和验证日期可追溯。

到这里，Gemini CLI 栏目就从“工具介绍”变成了一套可维护的教程工作流。

交付摘要模板

最后交付时至少说清：

• 修改了哪些路径。
• 每批验证跑了什么。
• 哪些官方来源已复核。
• 是否有并发改动被避开。
• 哪些构建或部署动作还没做。

这能让下一位 agent 或人工编辑直接接手，而不是重新猜当前进度。

复盘标准

真实项目做完后，要复盘三件事：官方来源是否还需要定期刷新，验证命令是否覆盖内容和构建，是否留下了可复用的 Skill、command 或 checklist。只有把这些沉淀下来，下一次新增栏目才会更快，而不是重新靠口头经验。

复盘还要看并发协作是否顺畅：有没有覆盖别人文件，有没有全局验证失败，有没有因为导航或断点遗漏导致上线后页面不可用。真实项目的质量，最终体现在这些细节里。

如果这些问题反复出现，就应该把流程沉淀成 checklist 或 command，而不是继续靠记忆提醒。

这份 checklist 应该进入仓库文档或团队规则，而不是只留在一次会话总结里。能被后来者直接复用，才算真实项目流程完成。

官方资料

• 文件管理教程：docs/cli/tutorials/file-management.md
• 自动化教程：docs/cli/tutorials/automation.md
• 任务规划（todos）：docs/cli/tutorials/task-planning.md
• 会话管理：docs/cli/tutorials/session-management.md
• 上下文与记忆：docs/cli/tutorials/memory-management.md

回到入口