# References 目录 Agent 指南

## 目录职责

`docs/references/` 存放工程实践、技术栈、质量门禁、模板和检查清单。

这里的文档回答：

- 项目应该如何组织。
- AI 编程应该如何设置硬门禁。
- 常见技术栈如何选择和组合。
- 工程经验如何变成可执行清单。

## 文件地图

```text
references/
├── README.md  # 索引入口：参考资料导航
├── project-architecture-template.md
├── python-project-skeleton.md
├── enterprise-architecture-template.md
├── modern-enterprise-architecture-template.md  # 现代企业数字化平台、版本治理、版本控制面、基线版本策略、发布通道、兼容性与冻结控制总账、基线生产变更、发布编排、变更冲突与失败恢复总账、基线事故、问题、纠正行动与复发防止总账、基线数据产品质量、契约违约、运行血缘与可观测性总账、基线工程质量、测试证据、缺陷与发布验证总账、基线人员能力、培训、职责履职与职责分离总账、基线业务结果、价值实现与组合收益总账、基线价值流、关键旅程与端到端流程总账、基线架构视图、运行拓扑与依赖影响总账、基线质量属性、架构驱动与权衡决策总账、基线架构原则、约束、反模式与例外执行总账、基线安全配置、加固姿态与配置漂移修复总账、基线漏洞、暴露面与修复验证总账、基线威胁建模、攻击面与安全风险总账、基线容量、性能、弹性伸缩与成本效率总账、基线服务可靠性、SLO、错误预算与可观测性总账、基线备份、恢复、灾备与可恢复性验证总账、基线密码材料、密钥、证书与秘密生命周期总账、基线资产关键性、数据分类与风险分级总账、基线身份权限、特权访问与工作负载身份总账、基线处理活动、个人数据清单与 RoPA 覆盖总账、基线隐私权利请求、同意偏好与合法基础执行总账、基线记录留存、法律保全与可防御删除总账、基线监管与合规义务可追溯总账、外部标准版本锁定、可执行标准、执行控制面、门禁决策、RACI、可靠性分级、仓库拓扑、迁移弃用、审计证据、微服务容器 GitOps、AI 原生能力、供应链安全和联邦治理蓝图
├── common-sense.md  # AI 编程和工程交付前的最低判断线
├── dataset-first-data-service.md
├── code-organization.md
├── development-experience.md
├── quality-gates-and-pitfalls.md
├── low-level-program-logic.md
├── technology-stack.md
├── AGENTS.md  # 本目录操作规则
```

## 修改规则

- 继承 `docs/AGENTS.md` 的 README 结构契约：H1 后直接进入 `## 字多不看`，再按 `快速导航 -> 完整细粒度目录 -> 使用方式 -> 正文` 排列。
- 新增参考资料时，优先写入对应独立主题文档，并同步更新 `README.md` 索引。
- 检查清单、模板、质量门禁和经验类内容优先进入对应独立文档，避免重新塞回 README。
- 技术选型、技术栈组合和学习路径优先维护在 `technology-stack.md`。
- 不在本目录写一次性研究笔记；新技术判断应先放入 `research/`。
- 不在 README 正文中写 `和其他目录的边界` 或 `维护规则`；维护者规则只写本文件。

## 质量要求

- 参考文档必须可执行、可检查、可复用。
- 门禁类内容尽量转成测试、CI、脚本、schema、类型或检查清单。
- 不确定项必须标注 TODO，不能编造成熟结论。
- 提交前必须运行 `make sync-doc-toc` 和 `make test`，确保锚点、链接和目录结构一致。