工具栈和系统边界
目的
定义工程操作系统中每类工具负责什么。通用原则是：成熟工具解决通用能力，自研精力放在核心产品、业务逻辑和团队闭环上。后续如果接入 Agent，再补 Agent 协作控制面。
推荐工具栈
| 系统 |
首选工具 |
负责什么 |
说明 |
| 源码管理 |
GitHub |
仓库、PR、分支保护、CODEOWNERS |
代码事实来源。 |
| 工作跟踪 |
Linear |
产品工作、bug、技术债、cycle、project |
Jira 适合更重的企业流程。 |
| 文档 |
Notion 或 Lark Docs/Wiki |
手册、spec、会议纪要、wiki |
代码邻近文档仍应放 repo。 |
| 沟通 |
Slack 或 Lark Messenger |
日常协作、事故群、发布通知 |
如果公司采用 Lark 套件，可用 Lark 替代 Slack/Notion 的协作层。 |
| 轻量流程/表单 |
Lark Base / Approval |
intake 表单、发布 checklist、事故 action 表 |
适合内部流程，不替代 GitHub/CI 事实。 |
| CI/CD |
GitHub Actions |
lint、typecheck、test、build、migration、smoke |
可替换为 GitLab CI、Buildkite 等。 |
| Monorepo |
pnpm + Turbo |
构建图、dev task、test task |
可替换为 npm/yarn/Nx/Bazel 等。 |
| 本地环境 |
Docker Compose |
Postgres、API、Web、本地集成 |
也可使用 Dev Container 或本地脚本。 |
| 后续 Runtime daemon |
Go service |
自动化 claim/run loop、本地执行、runtime pairing |
后续 Agent 阶段再建设。语言不限，关键是 claim、heartbeat、隔离和回传。 |
| 数据库 |
Postgres + Drizzle |
平台事实和 migration |
ORM 可替换，migration 必须可审查。 |
| 可观测性 |
Sentry + Grafana/Loki/Prometheus/Tempo |
错误、指标、日志、trace |
Datadog 是付费一体化替代；Lark 只适合接收告警。 |
| 密钥 |
1Password 起步，Vault 进阶 |
开发者密钥、服务密钥、审计 |
小团队先用 1Password；复杂后上 Vault。 |
| Feature flag |
LaunchDarkly 或 Unleash |
灰度发布、kill switch |
风险功能必须有快速关闭手段。 |
| 安全扫描 |
GitHub Advanced Security / Dependabot / Semgrep |
依赖和代码扫描 |
PR 和定时任务都应跑。 |
参考实现映射
| 参考资产 |
操作系统角色 |
.github/workflows/ci.yml |
CI 质量门禁 |
docker-compose.yml |
本地和 smoke 环境 |
repo-level check command，例如 pnpm check |
合并前统一检查命令，通常聚合 format/lint/typecheck/unit test/build |
turbo.json |
Monorepo task graph |
packages/db |
DB migration owner |
services/runtime-daemon |
后续自动化 Runtime 执行层 |
SCM smoke/witness scripts，例如 scripts/github-*smoke* |
验证 GitHub/GitLab 等外部集成的最小真实路径 |
Provider smoke，例如 smoke:codex |
后续验证真实 agent/provider 集成能完成一次受控 run |
工具负责人规则
- Linear/Jira 负责计划中的工作和状态。
- GitHub/GitLab 负责代码、PR 和 CI 事实。
- Notion/Lark Wiki 负责手册、会议纪要、协作型文档。
- Repo docs 负责架构、模块契约、测试、runbook、技术规范。
- Slack/Lark 负责时效性沟通，不负责永久决策。
- Postgres 负责平台事实。
- 可观测性工具负责运行时事实。
- Secret manager 负责凭证；
.env.local 只是本地投影。
三角色工具责任
| 角色 |
负责工具边界 |
| 产品负责人 |
工作跟踪、产品文档、验收记录、用户反馈入口 |
| 技术负责人 |
Git、PR、代码规范、架构文档、质量门禁 |
| 平台 / 资深工程师 |
CI/CD、本地环境、监控、日志、密钥、发布和排障工具 |
工具选型可以替换，但这三类责任不能混在一起。比如 Lark 可以通知和审批，但不能替代 PR、CI、监控或密钥系统的事实来源。
集成契约
| 流程 |
集成方式 |
| Linear issue -> GitHub branch |
分支名和 PR 标题包含 issue id |
| GitHub PR -> Linear 状态 |
GitHub integration 或自动化更新状态 |
| CI 结果 -> PR 门禁 |
保护分支要求 required checks |
| 发布 -> Slack/Lark |
发布 bot 推送 owner、version、rollback |
| 事故 -> Slack/Lark + Linear |
事故群协作，action items 进入 Linear |
| 错误峰值 -> issue |
Sentry/Grafana 告警创建或关联事故 |
| 密钥请求 -> audit |
1Password/Vault 记录访问或 service account 使用 |
如果团队标准化使用 Lark/飞书，可以这样替换协作层：
| 流程 |
Lark 映射 |
| 发布通知 |
Lark 群机器人发送发布卡片 |
| 事故房间 |
Lark 事故群 + 置顶事故文档 |
| Intake 表单 |
Lark Base 表单或 Approval 表单 |
| 周计划纪要 |
Lark Docs/Wiki |
| 轻量审批 |
Lark Approval 做内部 sign-off，技术门禁仍在 GitHub/CI |
| 告警路由 |
Grafana/Sentry webhook -> Lark bot |
反模式
- 不要在 Slack/Lark thread 里追踪正式任务。
- 不要只在会议里保存架构决策。
- 不要把本地机器的构建结果当作唯一证据。
- 不要让 CI 可选。
- 不要把生产密钥放进 repo、CI log、群聊或文档。
- 后续不要让 Agent 工具访问任何人类无法解释的系统。
下一步阅读
读完或填完这份文档后，通常继续看：