明智的开发者不会「先写代码再碰运气」。他们把新项目推进到头脑风暴、团队讨论、原型、图表、提案、ADR、MR/PR 与 GitOps——并由 Review Bot 自动生成 PR 评论，让人类把时间花在真正重要的事上。这就是生产级手册。FDE 可以搭建这套体系；若你要设计并为之辩护，Claude Architect Certification 值得追求。
1. 新项目上的「明智」意味着什么
明智不是更多会议。而是尽早进行低成本学习，并让晚期的高代价错误变得罕见。下列顺序使每一步都缩小下一步的爆炸半径：
Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
→ Implement in small slices → MR/PR + Review Bot → Merge
→ GitOps promote (dev → staging → prod) → Observe → Iterate
仅在有意时跳过步骤（例如单行配置修复）。任何可能进入生产的变更都不要跳过 Review Bot + CI。
2. 头脑风暴（先独自，再结构化）
在占用任何人时间之前，先独自花 30–90 分钟：
- 结果： 完成时必须成立的用户/业务变化是什么？
- 约束： 时间、预算、合规、现有平台、团队技能。
- 非目标： v1 不会构建什么（保护范围）。
- 风险： 数据、安全、性能、供应商锁定、运维负担。
- 成功指标： 延迟、错误率、采用度、成本——选两个真正重要的。
记成短笔记（Notion/Confluence/仓库中 docs/ideas/ 下的 markdown）。没有书面产物的头脑风暴只是会蒸发的对话。
3. 与同事讨论
邀请最小有用圈层：一位将与你一起实现的同伴、一位相邻系统负责人，以及（需要时）安全或 SRE。保持明智的规则：
- 限时 （25–45 分钟）。以决策或开放问题结束——不是 vibe。
- 对选项异议，不对人。 强制「方案 A vs B vs 推迟。」
- 指定记录员。 笔记成为提案的种子。
- 禁止沉默否决。 若有人不安，稍后在 ADR 中把顾虑写成风险。
异步也行：短 RFC 评论串往往胜过会议——但仍需有人闭环。
4. 原型（带到期日的 spike）
不确定性高时做原型：新 API、不熟悉的云服务、性能问题，或 AI/代理行为。明智规则：
- 在工单中命名为 spike；设定日历截止（通常 1–3 天）。
- 代码放在一次性分支或
spikes/文件夹；不要打磨。 - 用 10 条要点写下所学——尤其是失败之处。
- 决定：晋级（重构进产品）、重写或放弃。
没有 ADR 就悄悄变成生产的原型，是团队继承意外架构的方式。
5. 图表（足以争论）
不需要 UML 长篇。优先三张各占一屏的草图：
| 图表 | 回答 |
|---|---|
| 上下文（C4 L1） | 谁与谁通信？信任边界？ |
| 序列 | 快乐路径 + 一条失败路径 |
| 部署 | 运行位置；配置与密钥如何流动 |
把 Mermaid 或图片存在提案旁（docs/architecture/）。ADR 变更时更新图表——过时图片比没有更糟。
6. 提案（轻量 RFC）
好提案一到三页：
- 问题与为何现在
- 考虑的选项（至少两个）
- 推荐及理由
- 影响：安全、成本、运维、迁移
- 发布与回滚
- 开放问题
请评审并给出明确截止日期。批准（或带修订批准）后，把决策写成 ADR——不要把「真相来源」留在聊天里。
7. ADR — Architecture Decision Records
ADR 是按约定不可变的短决策记录。模板：
# ADR-00XX: Title Status: Proposed | Accepted | Superseded by ADR-00YY Date: YYYY-MM-DD Deciders: @alice @bob ## Context What forces are in play? ## Decision What we will do. ## Consequences Positive, negative, and follow-ups. ## Alternatives considered Option A — why not Option B — why not
把 ADR 放在 git（docs/adr/）。从 PR 链接它们。用 supersede 而非改写历史——未来的你需要轨迹。
8. MR 与 PR — 交付单元
MR（Merge Request，GitLab）与 PR（Pull Request，GitHub/Bitbucket）是同一概念：可评审的变更集。明智习惯：
- 小： 理想情况下有意义 diff <400 行；按垂直切片拆分。
- 单一意图： 一个功能、修复或杂务——不是「杂项」。
- 描述： 为何、如何测试、截图/日志、风险、回滚。
- 链接： 工单 + ADR + 设计图。
- 先 Draft 想要早期反馈且不暗示「已可合并」时。
- 绝不强制合并 绕过红色 CI 或未解决的高严重度 bot 发现，除非有书面例外。
示例 PR 正文清单
## Summary - … ## Test plan - [ ] Unit tests - [ ] Manual path … - [ ] Feature flag / config … ## Risk & rollback - Risk: … - Rollback: revert this PR / GitOps revert commit … ## References - ADR-00XX - Ticket ABC-123
9. Review Bot 用法 — 自动生成的 PR 评论
Review Bot 是在每个 MR/PR 上发布行内评论与摘要的自动化审查者。它不替代人类；它前置乏味与危险事项。
9.1 Bot 应评论什么
- 安全：注入、授权缺口、密钥泄漏、不安全默认值
- 正确性：空路径、竞态、损坏的迁移
- 测试：新分支缺覆盖、滥用快照
- API/契约：破坏性变更未升版本
- 运维：缺超时、无幂等、无限重试
- 风格仅当逃过 formatter/linter（避免噪声）
9.2 如何简化开发者生活
- 作者打开 PR → bot 在数秒到数分钟内运行。
- 作者在请求人类前先修复或回复 bot 线程。
- 人类审查者阅读 bot 摘要，并聚焦设计与产品风险。
- 更少「nit」轮次；更快合并；更少因漏掉陷阱导致的周五晚事故。
9.3 典型设置选项
| 方法 | 说明 |
|---|---|
| SaaS Review Bot（如 CodeRabbit、厂商 bot） | 启用快；调整严重度与路径过滤 |
| Cursor Bugbot / IDE 关联审查 | 在以 Cursor 为中心的团队中对 PR diff 很强 |
| 自定义 GitHub Action + Claude / LLM | 完全控制；需要提示词 + 策略 + 成本上限 |
| 分层流水线（lint → SAST → LLM） | 最佳生产姿态——见 AI 代码审查流水线指南 |
9.4 让 bot 保持有用的策略
- 严重度标签：blocker / should-fix / nit —— nit 不得阻塞合并。
- 忽略生成路径（
vendor/、lockfile 噪声、protobuf dumps）。 - 安全敏感路径（
auth/、infra/、IAM）需要人类批准。 - 记录误报；每月反馈进忽略规则。
- 切勿让 bot 成为生产关键服务的唯一审查者。
9.5 最小 GitHub Action 草图
# .github/workflows/review-bot.yml
name: review-bot
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Review Bot
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
run: |
# Fetch diff, call your review CLI, post review comments via gh api
./scripts/review-bot.sh
实现 review-bot.sh：计算 PR diff，用严格 system prompt（安全 + 正确性优先）调用模型，并通过 GitHub/GitLab API 发表评论。限制 token；若成本敏感可跳过 draft。
10. 面向生产级质量的 GitOps 最佳实践
GitOps 意味着：期望状态存在于 git；协调器（Argo CD、Flux 等）使集群匹配；晋级是一次 merge；回滚是一次 revert。
- 分离应用代码与环境配置 （或清晰目录：
apps/vsenvs/dev|staging|prod）。 - 不以 kubectl apply 到 prod 作为快乐路径——仅 break-glass 且可审计。
- 渐进交付： dev 自动同步；prod 手动或门控同步。
- 镜像 digest 优于 prod 清单中的可变标签。
- Policy as code： 用 OPA/Kyverno 约束权限、仓库、资源限制。
- 签名提交 / 出处 在威胁模型要求时启用。
- 同步后观察： 健康检查、错误预算、就绪时的自动回滚钩子。
代码质量不只是「干净函数」。也是变更如何进入生产。GitOps 使该路径可审查、可逆、可重复。
11. 端到端质量门（为生产优化）
Local: pre-commit (fmt, lint, secrets) + unit tests PR open: CI (build, test, SAST) + Review Bot comments PR merge: human approve + branch protection + required checks Main: build immutable artifact (image digest) GitOps: update env repo / overlay → sync → verify Prod: SLOs + alerts + runbook linked from ADR/PR
12. FDE 角色 — 谁搭建这套系统
Forward Deployed Engineer（前线部署工程师）非常适合在真实团队中安装明智开发者体系：
- 仓库模板：
docs/adr/、PR 模板、CODEOWNERS、分支保护 - Review Bot + secrets + 成本控制
- CI 必过检查与环境保护
- GitOps 应用（dev/staging/prod）与晋级文档
- 两周辅导：首个 ADR、首个 bot 调优 PR、首次 GitOps 回滚演练
FDE 主导单个产品仓库赋能的参考日历：脚手架与 bot 策略 1–2 周；GitOps 晋级路径与干跑回滚再 +1–2 周。文化变革更久——衡量合并时间与逃逸缺陷，而非工具安装数。
13. Claude Architect Certification — 值得追求
若你设计人类与 AI 代理共同编写代码的系统，Claude Architect Certification 值得追求。它表明你能够：
- 架构 AI 辅助交付，且不把模型当作绝对正确
- 为代理工作流规定审查策略、护栏与评估
- 向干系人沟通权衡（延迟、成本、隐私、准确性）
- 在 AI 工具旁辅导团队的 ADR、PR 纪律与生产门
把证书与真实交付配对：搭建 Review Bot、写三份 ADR、跑一次 GitOps 回滚演练。没有实践的纸面不能让你明智；实践加上共同语言可以。
14. 反模式（不明智的样子）
- 巨型 PR 写着「WIP please approve ASAP」
- 架构只在 Slack 决定，从不进 ADR
- 无测试的原型合入生产
- 因「太啰嗦」而关闭 Review Bot
- 在 GitOps 外热修生产且无回退计划
- 人类重复 bot 已抓住的 formatter nits
15. 新项目可复制启动清单
- 创建
docs/ideas/、docs/architecture/、docs/adr/ - 添加 PR/MR 模板 + CODEOWNERS
- 启用 pre-commit + CI 必过检查
- 安装 Review Bot；调整路径过滤与严重度
- 写 ADR-0001：「We use GitOps for deploy」
- 定义环境与晋级规则
- 安排 30 分钟回滚 game day
- 为第一个月辅导预约 FDE 时间；考虑给负责人考 Claude Architect Certification
16. 结语
明智的开发者把新项目当作一串学习产物——笔记、图表、提案、ADR——再通过 Review Bot 守护、GitOps 晋级的小型 MR/PR交付。这就是在不让团队陷入无尽 nit 的前提下，把代码质量优化到生产级的方式。让 FDE 铺好轨道；让认证架构师在 AI 加速写码速度时，让系统保持诚实。
发布方 Workstation.
