# 开发规范

> **最后更新**: 2026-04-06

本目录记录架构决策和开发规则。技术栈执行细则在 `.agents/skills/` 对应 skill 的 references 中。

## 元规则

| 文档 | 内容 |
|------|------|
| [产品哲学](./00-product-philosophy.md) | 二常驻 + 一临时（对话/展示/确认）；约束该不该做，优先级高于其他 standards |

## 架构

| 文档 | 内容 |
|------|------|
| [系统架构](./01-system-architecture.md) | 整体架构、技术栈、部署拓扑 |
| [前端架构](./03-frontend-architecture.md) | 路由分组设计、分层职责 |
| [后端架构](./02-backend-architecture.md) | 三层架构（Core/Engines/Modules） |
| [数据库架构](./04-database-architecture.md) | 多 Schema 设计、命名约定 |
| [数据分层与元数据策略](./16-data-layering-and-metadata-policy.md) | 三层架构（L1 平台公共 / L2 领域主 / L3 业务）+ 默认不立元数据驱动 L4 + 加回 L4 的明确触发条件 |

## 流程

| 文档 | 内容 |
|------|------|
| [开发工作流](./05-development-workflow.md) | AI-first 方法论、开发阶段、测试策略、Git 规范 |
| [Agent Pool（开发 worktree 池）](./10-agent-pool.md) | 多 agent 并行的 worktree 池机制：原理、组成、不变量、设计决策 |
| [发布管理](./08-release-management.md) | 版本号规范、更新日志格式 |
| [文档系统规则](./06-documentation-system.md) | 文档编号、命名、依赖顺序 |
| [PR 描述书写规范](./13-pr-description-spec.md) | v2 两层模板设计（当下决策 + 未来回顾）+ 6 条元规则（含必填 `Closes #N` + push 后 PATCH body）+ 反例正例对照 |

## 专项

| 文档 | 内容 |
|------|------|
| [日期时间处理](./07-datetime-handling-guide.md) | UTC 存储、ISO 传输、纯日期不转换 |
| [故障 / Bug 解决方法论](./11-troubleshooting-methodology.md) | 第一性原理 3 层拆解；P0/P1 复盘 6 段强制模板 |
| [5 条元根因规则](./12-five-meta-rules.md) | 契约面 / 依赖图 / 环境一致 / 实测完工 / 监控告警；docs 落地 + 工程化保险依赖 |