技术规范
目的
定义团队成员都能遵守的稳定工程规则。先让人类工程师看得懂、做得到，再考虑自动化执行。
仓库基线
每个仓库应包含：
| 文件 | 目的 |
|---|---|
README.md |
仓库做什么、如何开始、关键文档入口 |
CONTRIBUTING.md |
开发流程 |
docs/PROJECT.md |
项目入口、owner、环境、监控、发布和回滚入口 |
docs/ARCHITECTURE.md |
系统总览 |
docs/TECH_STACK.md |
技术选型、版本、替代方案、升级策略 |
docs/DEPENDENCIES.md |
上游、下游、第三方和基础设施依赖 |
docs/MODULE_CONTRACTS.md |
模块边界和 owner |
docs/SERVICE_CONTRACTS.md |
服务 API、鉴权、事件、SLO、运维入口 |
docs/TESTING.md |
测试策略和命令 |
docs/RUNBOOK.md |
生产运维 |
docs/SECURITY.md |
密钥、权限、漏洞处理 |
实际仓库可能只具备部分 docs/ 文件。缺失文档应在真正需要运营时补齐，不必为了形式一次性写满。但生产项目至少要有 docs/PROJECT.md，否则新人和接手人不知道从哪里开始。
项目架构文档包见 41-项目架构文档包-project-architecture-pack.md。草台团队至少应先补 PROJECT.md、ARCHITECTURE.md、TECH_STACK.md、DEPENDENCIES.md，让新人能理解项目入口、系统边界、技术选型和上下游风险。
三角色维护边界
| 角色 | 维护什么 | 不能缺什么 |
|---|---|---|
| 技术负责人 | 架构、代码规范、API/DB 规则、高风险路径 | 技术门禁和 review owner |
| 产品负责人 | 产品文档、验收标准、用户可见行为 | Business Approver 和反馈入口 |
| 平台 / 资深工程师 | 开发环境、CI、模板、脚本、runbook | 可复制执行的命令和排障路径 |
代码规范
最低规则：
- Formatter 和 linter 必须执行。
- 静态类型语言必须通过 typecheck 或 compile check。
- 动态语言必须通过 lint、可选类型检查和测试。
- Error response 使用一致 schema。
- 结构化日志包含 request id、actor、resource id、error code。
- 数据库 migration 必须 review。
- Secret 不得出现在源码、日志、截图或 issue comment。
- 外部依赖必须说明用途。
不同语言应把这些规则落到明确命令：
| 技术栈 | 必备检查示例 |
|---|---|
| TypeScript | pnpm lint、pnpm typecheck、pnpm test |
| Go | gofmt -l .、go vet ./...、go test ./... |
| Python | ruff check .、mypy . 或 pyright、pytest |
| Rust | cargo fmt --check、cargo clippy -- -D warnings、cargo test |
| Java/Kotlin | ./gradlew check、./gradlew test、./gradlew build |
API 规范
每个 API endpoint 需要定义：
| 字段 | 要求 |
|---|---|
| Auth | 谁能调用 |
| Input | schema 和校验 |
| Output | 稳定返回结构 |
| Error | 区分业务错误和系统错误 |
| Idempotency | create、webhook、retry、callback 必须考虑 |
| Audit | 写操作记录 actor 和 target |
| Pagination | list endpoint 必须明确分页 |
数据库规范
每张表应定义：
- Owner。
- 生命周期 / 状态值。
- 唯一性规则。
- 外键或显式引用规则。
- 索引依据。
- 数据保留策略。
- Migration rollback 策略。
每个仓库都应提供稳定 migration 入口。如果使用 Drizzle，可用 pnpm db:migrate；Python 常见入口是 Alembic/Django migration；Java/Kotlin 常见入口是 Flyway/Liquibase；Rust 常见入口是 SQLx/Diesel migration。无论使用什么工具，都必须能在 CI 或测试数据库里验证 migration 可执行。
模块契约模板
使用 templates/模块契约-module-contract.md。
架构变更文档要求
这些变更必须同步更新架构文档包：
- 新增或删除服务、worker、job、cron。
- 模块职责或边界变化。
- 技术栈、框架、数据库、队列、缓存、部署方式变化。
- 新增或修改上游 / 下游 / 第三方依赖。
- API、webhook、事件、状态机变化。
- 数据库 schema、数据 owner、保留策略变化。
- 自动化或 Agent runtime、权限、scope、approval 策略变化。
没有对应文档更新的架构变更，reviewer 应要求补齐。
后续 Agent 就绪要求
这一节在人类技术规范稳定后再看。
Agent 需要这些规范以机器可读或易引用的形式存在：
- 模块契约。
- API 契约。
- 各模块测试命令。
- 禁止修改路径。
- 日志和错误约定。
- Migration 规则。
- 技术选型和上下游依赖。
下一步阅读
读完或填完这份文档后，通常继续看：
- 33-测试和质量-testing-quality.md：技术规范明确后，继续看不同语言下的质量门禁。