在撰写项目介绍文档时，最令人头疼的是什么？技术负责人仅扫一眼开头，看到“高性能”“易扩展”“模块化设计”等空洞词汇，便会直接关闭页面——因为这些套话既无法通过立项评审，也无法让新同事快速上手实践。本文将从实战角度，分享如何将文档写得真正有价值。

第一步：剔除所有无主语、无具体动作的形容词短语

打开你正在编写的项目介绍文档，通读三遍，将那些不包含具体执行者、无法指向可验证动作的词汇全部删除。例如：“具备高可用性”→删除；“支持灵活配置”→删除；“采用微服务架构”→保留，但必须紧接着写明“谁在什么环节调用哪个服务”。如果跳过这一步，后续添加再多细节也只是空中楼阁。完成删除后，全文剩余形容词不超过2个。

第二步：使用真实角色与具体动作重写开头段落

方法一：以“新人入职第一天的实际操作”为锚点重写首段
不要写“本系统面向企业级用户”，而应写：“运维同学入职第一天，执行 trae deploy --env=prod --region=shanghai，5分钟内完成灰度发布并收到钉钉告警确认。”

方法二：利用故障场景反向推导价值
不要写“提供完善的监控能力”，而应写：“当订单支付回调超时率突增至12%时，值班工程师打开 /dashboard/trace?service=pay-gateway，30秒内定位到是Redis连接池耗尽，而非下游接口问题。”

第三步：补充中文团队实际卡点的三类关键信息

① 本地联调路径：
前端开发者拉取代码后，执行 npm run dev → 打开 http://localhost:8080/mock/order/list 查看模拟返回数据；后端开发者需先启动 docker-compose -f docker/mock.yml up -d。

② 环境切换方式：
修改 src/config/env.ts 中的 API_BASE_URL 字段，从 https://api-dev.trae.cn 切换为 https://api-prod.trae.cn；切换后务必运行 yarn test:e2e --env=prod 验证核心链路。

③ 报错速查表：
报错信息 “ERR_CONNECTION_REFUSED” → 检查是否漏启动 mock 服务；
报错信息 “401 Unauthorized” → 核对 .env.local 中的 VUE_APP_TOKEN 是否为空或已过期；
报错信息 “Module not found: Error: Can't resolve 'lodash/debounce'” → 运行 npm install lodash@4.17.21 锁定版本（因内部Harbor镜像仅缓存该版本）。