PROJECT_PROFILE.md
文件定位：项目语义与历史背景的权威说明文档 主要受众：首次参与本项目的 AI 与人类开发者 核心目标：用尽量少但稳定的信息，帮助 AI 与新成员快速建立对项目“是什么、为什么这样、哪里不能动”的整体认知。
1. 项目一句话说明（TL;DR）
用一句话回答：这个项目是做什么的，解决什么核心问题。
示例：
本项目是一个面向企业内部的统一任务调度与执行平台，用于承载历史系统中的定时任务、异步补偿与批处理逻辑。
2. 项目背景与存在原因
2.1 为什么要有这个项目
-
解决的业务问题：
<问题 1><问题 2>
-
项目出现前的主要痛点：
<历史痛点>
2.2 当前项目在系统体系中的位置
- 上游系统：
<依赖它的系统> - 下游系统：
<它依赖的系统> - 是否是关键路径系统：
是 / 否
3. 当前阶段与总体目标
3.1 当前阶段定位
-
项目状态：
- ☐ 存量维护为主
- ☐ 增量功能为主
- ☐ 重构 / 收敛阶段
-
技术目标优先级：
- 稳定性
- 向后兼容
- 可观测性
- 性能
3.2 明确“不追求”的目标
非目标的明确声明，可以显著降低 AI 的错误发挥。
-
不做：
<例如：技术栈升级><例如：领域模型重构>
4. 核心业务概念与术语表（必填）
本节用于统一语义，避免 AI 或新成员误解名词。
| 术语 | 含义 | 备注 |
|---|---|---|
<TermA> |
<解释> |
<是否历史遗留> |
<TermB> |
<解释> |
<注意点> |
5. 核心业务流程（高层）
只描述 稳定且长期存在的主流程，不写实现细节。
示例：
- 用户 / 上游系统发起请求
- 请求经过校验与路由
- 核心服务执行业务逻辑
- 状态持久化
- 结果回传或异步通知
6. 模块划分与职责边界
回答“模块是如何分工的”，而不是代码结构细节。
| 模块 | 核心职责 | 备注 |
|---|---|---|
<ModuleA> |
<职责说明> |
<是否稳定> |
<ModuleB> |
<职责说明> |
<是否历史包袱> |
7. 历史演进与关键决策（非常重要）
本节用于解释：为什么现在看起来“不优雅”。
7.1 重要演进里程碑
<年份 / 版本>：<发生了什么变化><年份 / 版本>：<引入了哪些妥协>
7.2 关键历史决策说明
| 决策 | 当时原因 | 现在是否仍然有效 |
|---|---|---|
<决策 A> |
<原因> |
是 / 否 / 部分 |
8. 已知历史包袱与妥协点
明确告诉 AI：哪些地方“不要碰”，以及“为什么”。
-
不可轻易修改的设计：
<说明>
-
已知技术债：
<说明>
-
理想方案 vs 现实方案：
<对比>
9. 稳定性与风险关注点
本节用于标记高风险区域。
-
高风险模块：
<模块 / 包路径>：<风险原因>
-
常见事故类型：
<事故类型>→<诱因>
10. 与其他文档的关系
- GEMINI.md：定义 AI 行为与工程约束
- DESIGN.md：定义 本次需求的确定性实现方式
本文件不描述“如何实现”，只描述“为什么这样存在”。
11. 维护说明
- 本文档维护责任人：
<角色 / 团队> -
更新原则：
- 项目定位变化时必须更新
- 重大历史决策调整时必须更新
12. 最后声明
本文件追求的是：
- 稳定性（不会频繁变动）
- 真实性（反映真实历史，而非理想设计）
如果本文档与代码行为冲突，请优先相信代码，并补充修正文档。
说明
模板的设计目标非常明确：不是“项目介绍”，而是“项目世界观压缩包”。
下面我从设计意图 + 使用建议 + 和 GEMINI.md 的协同关系三个角度，帮你快速判断它在体系中的价值。
一、这份 PROJECT_PROFILE.md 的核心定位
一句话概括：
它回答“为什么项目会变成现在这样”，而不是“现在应该怎么写代码”。
因此它刻意做到三点：
-
稳定性优先
- 不写短期需求
- 不写实现细节
- 不随功能迭代频繁修改
-
历史真实性优先
- 接受“不优雅”
- 接受“妥协方案”
- 明确哪些是技术债、哪些是禁区
-
语义统一优先
- 术语表是必填项
- 防止 AI / 新人对同一名词产生不同理解
二、你在真实项目中的推荐填写顺序（很重要）
不要一次性填满，顺序比完整性更重要。
第一阶段（最低可用）
优先完成以下章节：
- §1 项目一句话说明
- §4 核心业务概念与术语表
- §6 模块划分与职责边界
- §8 已知历史包袱与妥协点
👉 这一版就已经可以明显降低 AI 的误判率。
第二阶段（增强理解）
补充：
- §2 项目背景与存在原因
- §7 历史演进与关键决策
- §9 稳定性与风险关注点
👉 这一版开始让 AI 理解“为什么不能乱改”。
第三阶段（工程级成熟）
补充：
- §3 当前阶段与总体目标
- §11 维护说明
👉 到这一步，它已经是项目级长期资产。
三、它与 GEMINI.md / DESIGN.md 的分工关系（非常关键）
你现在的三份文档，职责边界已经非常清晰：
| 文档 | 回答的问题 |
|---|---|
| GEMINI.md | 你能不能这么做？ |
| PROJECT_PROFILE.md | 为什么项目会这样？ |
| DESIGN.md | 这一次具体要怎么做？ |
一个非常重要的使用原则是：
PROJECT_PROFILE.md 不能包含“本次需求的实现方案”。 否则它会变成劣化版 DESIGN.md，反而误导 AI。
四、一个你已经在“隐式使用”的高级技巧
从你前面的描述来看，你其实已经在做一件很高级的事：
用 PROJECT_PROFILE.md 限制 AI 的“问题空间”， 用 DESIGN.md 限制 AI 的“解空间”。
这正是历史项目中，AI 能够“稳而不乱”的关键。
