---
title: "真实项目贯穿实战"
description: "用一个真实项目流程串起 Gemini CLI：只读扫描、上下文沉淀、计划、修改、验证、checkpoint、headless 和 GitHub Action。"
verifiedAt: "2026-05-09"
---

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

> [!IMPORTANT]
> 真实项目里，质量来自流程约束：只读进入、明确归属、分批写入、每批验证、不中断别人改动。

## 场景

假设你要给一个文档站补一个新产品栏目。仓库里还有其他 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/`，暂停合并，不要覆盖。

## 并发协作表

| 情况 | Gemini CLI 应该怎么做 |
| --- | --- |
| 别人在改其他栏目 | 继续，只检查自己目录和全局验证 |
| 别人在改同一栏目不同文件 | 先确认文件归属，批次更小 |
| 别人在改同一文件 | 停止写入，等待人工协调 |
| 全局配置或导航被别人改 | 先读 diff，再决定是否需要同步 |
| 测试失败来自无关文件 | 记录失败，不顺手修别人改动 |

## 第五步：验证

先做目标目录检查：

`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 阻止跨栏目误改。

## 完整工作流

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

## 结束标准

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

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

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

## 交付摘要模板

最后交付时至少说清：

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

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

## 复盘标准

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

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

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

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

## 官方资料

- 文件管理教程：[docs/cli/tutorials/file-management.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/file-management.md)
- 自动化教程：[docs/cli/tutorials/automation.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/automation.md)
- 任务规划（todos）：[docs/cli/tutorials/task-planning.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/task-planning.md)
- 会话管理：[docs/cli/tutorials/session-management.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/session-management.md)
- 上下文与记忆：[docs/cli/tutorials/memory-management.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/memory-management.md)

## 回到入口

<Cards>
  <Card title="Gemini CLI 从原理到实战" description="回到本系列入口，复查 12 篇的整体学习路径。" href="/docs/gemini-cli/understanding" />
  <Card title="官方教程中文版" description="需要继续查命令、配置、MCP、模型、安全和自动化细节。" href="/docs/gemini-cli/official" />
  <Card title="故障排查与参考" description="真实项目执行中遇到认证、PATH、sandbox、版本和 package 问题时进入。" href="/docs/gemini-cli/official/08-troubleshooting-reference" />
</Cards>
