diff --git a/New-Project-Documentation-Setup.-.md b/New-Project-Documentation-Setup.-.md index 8ee5a1d..b859809 100644 --- a/New-Project-Documentation-Setup.-.md +++ b/New-Project-Documentation-Setup.-.md @@ -18,7 +18,25 @@ 把项目专用红线写入根目录或子目录 `AGENTS.md`。 -### 2. 识别子项目与交付单元 +### 2. 选择建设基线 + +确定技术方案前,优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”,不是强制采用开源项目,也不能只根据知名度、Star 数量或演示效果决定。 + +至少检查: + +- 核心功能、架构和支持平台是否匹配,哪些能力可以直接保留; +- 许可证是否允许预期的使用、修改、分发和商业模式;不确定时交由负责人或法律专业人员确认; +- 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性; +- 已知安全问题、依赖健康度、供应链风险和安全响应方式; +- 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护; +- 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发; +- 是否能够固定上游仓库和基线版本,并建立合并上游更新、兼容验证和退出方案。 + +满足适配、许可证、安全、维护和总成本条件时,优先在该基线上二次开发。不存在合适基线,或引入后会增加不可接受的许可证、安全、架构或维护风险时,可以从零开发,但必须记录排除候选项目和选择从零开发的主要原因。 + +采用开源基线时,在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单,不得把假设写成项目事实。 + +### 3. 识别子项目与交付单元 先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认: @@ -32,11 +50,11 @@ 把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元;多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`,但不因为技术栈不同自动拆仓,也不强制统一版本和发布周期。 -### 3. 建立 Gitea +### 4. 建立 Gitea 创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。 -### 4. 修改镜像配置 +### 5. 修改镜像配置 把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目;只保留核心主题映射,任务归档不逐页登记。 @@ -44,7 +62,7 @@ 不要把 PAT 写入配置。 -### 5. Agent 检查项目事实 +### 6. Agent 检查项目事实 Agent 只读检查: @@ -57,7 +75,7 @@ Agent 只读检查: 区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。 -### 6. 确定交付对象和文档 +### 7. 确定交付对象和文档 由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品,并为每类对象确定: @@ -69,7 +87,7 @@ Agent 只读检查: 按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档,使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建,不预建空白的用户手册、管理员手册或运维手册。 -### 7. 先创建线上 Wiki +### 8. 先创建线上 Wiki 至少创建或填写: @@ -85,9 +103,9 @@ Agent 只读检查: 10. Audience-Document-Template; 11. Task-Archive-Template。 -Home 给出建议阅读顺序;每个命令必须有预期结果;代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。 +Home 给出建议阅读顺序;每个命令必须有预期结果;代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。 -### 8. 人工确认 +### 9. 人工确认 项目负责人至少确认: @@ -98,7 +116,7 @@ Home 给出建议阅读顺序;每个命令必须有预期结果;代码地图 - 哪些修改属于高风险; - 交付对象、文档可见范围和外部信息边界。 -### 9. 导出镜像并检查 +### 10. 导出镜像并检查 ```powershell python dev_scripts/sync_wiki_docs.py @@ -118,6 +136,8 @@ python -m unittest discover -s tests -v - 常用功能从哪个目录和入口开始读; - 一个简单修改通常要改哪里、验证什么; - 哪些情况必须停止并交给 Agent 或负责人; +- 项目采用哪个建设基线,为什么适合二次开发,或者为什么选择从零开发; +- 采用开源基线时,上游仓库、基线版本、许可证、定制范围和升级策略是什么; - 项目包含哪些子项目和独立交付单元,各自怎样构建、测试和发布; - 跨子项目共享什么接口或契约,其唯一事实来源在哪里; - 项目需要向哪些岗位交付什么文档,以及哪些内容不能对外提供。