192 lines
9.2 KiB
Markdown
192 lines
9.2 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: New-Project-Documentation-Setup
|
||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.-
|
||
wiki_revision: 864d81b515b420d17fa4ff0fc7f528109b1a3d99
|
||
synchronized_at: 2026-08-16T11:38:04Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 新项目文档初始化
|
||
|
||
## 本页用途
|
||
|
||
从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。
|
||
|
||
## 初始化顺序
|
||
|
||
### 1. 建立项目边界
|
||
|
||
由项目负责人确认：
|
||
|
||
- 项目名称和一句话目标；
|
||
- 用户和主要使用场景；
|
||
- 技术栈和支持环境；
|
||
- Gitea 仓库、默认分支和维护者；
|
||
- 安全、权限、数据和发布红线。
|
||
|
||
把项目专用红线写入根目录或子目录 `AGENTS.md`。
|
||
|
||
### 2. 选择建设基线
|
||
|
||
确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。
|
||
|
||
至少检查：
|
||
|
||
- 核心功能、架构和支持平台是否匹配，哪些能力可以直接保留；
|
||
- 许可证是否允许预期的使用、修改、分发和商业模式；不确定时交由负责人或法律专业人员确认；
|
||
- 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性；
|
||
- 已知安全问题、依赖健康度、供应链风险和安全响应方式；
|
||
- 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护；
|
||
- 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发；
|
||
- 是否能够固定上游仓库和基线版本，并建立合并上游更新、兼容验证和退出方案。
|
||
|
||
满足适配、许可证、安全、维护和总成本条件时，优先在该基线上二次开发。不存在合适基线，或引入后会增加不可接受的许可证、安全、架构或维护风险时，可以从零开发，但必须记录排除候选项目和选择从零开发的主要原因。
|
||
|
||
采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。
|
||
|
||
#### 判断案例
|
||
|
||
以下案例用于说明判断方式，不代表必须选择某种技术或具体开源项目。
|
||
|
||
##### 案例一：适合基于成熟项目二次开发
|
||
|
||
计划开发企业内部管理系统。候选项目已经具备用户、权限、审计日志、基础数据管理和自动化测试；功能与目标架构基本匹配，许可证允许预期使用，项目持续维护，发布与升级流程完整，预计只需修改业务模块和界面。
|
||
|
||
- 结论：优先基于该项目二次开发。
|
||
- 原因：可以减少通用功能的开发和验证成本，定制范围可控。
|
||
- 记录：上游仓库、基线版本、许可证、保留功能、定制模块和上游升级方式。
|
||
|
||
##### 案例二：项目成熟但许可证不兼容
|
||
|
||
候选项目功能完整、维护活跃、文档充分，但许可证与当前产品的闭源分发、商业模式或交付条件不兼容。
|
||
|
||
- 结论：不采用该项目作为建设基线。
|
||
- 原因：技术成熟度不能消除许可证风险；不确定结论必须交由负责人或法律专业人员确认。
|
||
- 记录：候选项目、许可证限制、确认人员和排除原因。
|
||
|
||
##### 案例三：功能相似但改造成本过高
|
||
|
||
候选项目表面上覆盖大部分功能，但数据模型、权限体系和部署结构与目标项目差异很大，需要大量删除模块、重写主要接口，并长期维护上游冲突。
|
||
|
||
- 结论：不直接基于完整项目二次开发，可以评估只复用合适的组件或设计思路。
|
||
- 原因：二次开发的总成本、理解成本和长期维护风险已经高于自主实现核心业务。
|
||
- 记录：主要结构差异、改造估算、长期维护风险和最终选择。
|
||
|
||
##### 案例四：只复用成熟框架或组件
|
||
|
||
没有功能高度匹配的完整开源产品，但存在成熟的应用框架、更新组件、日志组件或通信库。
|
||
|
||
- 结论：从零开发业务功能，同时复用经过评估的成熟框架或组件。
|
||
- 原因：复用基础能力不等于必须采用完整产品，可以避免被不匹配的业务架构绑定。
|
||
- 记录：每个依赖的用途、版本、许可证、安全边界、升级方式和可替换方案。
|
||
|
||
每个案例的实际评估都必须记录候选项目、判断依据、最终选择、未采用原因，以及升级或退出方式。
|
||
|
||
### 3. 识别子项目与交付单元
|
||
|
||
先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认：
|
||
|
||
- 职责和目录边界；
|
||
- 技术栈、依赖和支持环境；
|
||
- 构建、测试和运行命令；
|
||
- 是否拥有独立版本号和发布方式；
|
||
- 适用的根目录或子目录 `AGENTS.md`；
|
||
- 与其他子项目共享的接口、数据或业务流程；
|
||
- 共享契约的唯一事实来源和兼容要求。
|
||
|
||
把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。
|
||
|
||
### 4. 建立 Gitea
|
||
|
||
创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。
|
||
|
||
### 5. 修改镜像配置
|
||
|
||
把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射，任务归档不逐页登记。
|
||
|
||
确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。
|
||
|
||
不要把 PAT 写入配置。
|
||
|
||
### 6. Agent 检查项目事实
|
||
|
||
Agent 只读检查：
|
||
|
||
- README、配置和依赖文件；
|
||
- 启动入口；
|
||
- 主要模块和目录规则；
|
||
- 测试、格式和静态检查命令；
|
||
- 日志、示例配置和测试数据；
|
||
- 已存在的接口、数据模型和状态。
|
||
|
||
区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。
|
||
|
||
### 7. 确定交付对象和文档
|
||
|
||
由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定：
|
||
|
||
- 需要完成的工作；
|
||
- 所需文档类型；
|
||
- 文档可见范围；
|
||
- 适用版本、负责人和验证人；
|
||
- 不得对外披露的内部信息。
|
||
|
||
按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。
|
||
|
||
### 8. 先创建线上 Wiki
|
||
|
||
至少创建或填写：
|
||
|
||
1. Home；
|
||
2. Project-Profile；
|
||
3. Architecture-and-Code-Map；
|
||
4. Business-Rules-and-Glossary；
|
||
5. Local-Development-and-Verification；
|
||
6. Common-Changes；
|
||
7. Troubleshooting；
|
||
8. Development-Workflow；
|
||
9. Delivery-Documentation-Guide；
|
||
10. Audience-Document-Template；
|
||
11. Task-Archive-Template。
|
||
|
||
Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。
|
||
|
||
### 9. 人工确认
|
||
|
||
项目负责人至少确认：
|
||
|
||
- 一句话目标和业务术语；
|
||
- 关键业务规则和状态；
|
||
- 权限、安全和数据边界；
|
||
- 真实运行、测试和部署命令；
|
||
- 哪些修改属于高风险；
|
||
- 交付对象、文档可见范围和外部信息边界。
|
||
|
||
### 10. 导出镜像并检查
|
||
|
||
```powershell
|
||
python dev_scripts/sync_wiki_docs.py
|
||
python dev_scripts/check_harness.py --strict
|
||
python dev_scripts/sync_wiki_docs.py --check
|
||
python -m unittest discover -s tests -v
|
||
```
|
||
|
||
只有线上 Wiki 确认后才导出核心 `docs/`。任务归档默认不导出；用户明确要求时再运行 `python dev_scripts/export_task_archives.py` 或加 `--all`。旧项目的任务归档快照不能带入新项目历史。
|
||
|
||
## 完成标准
|
||
|
||
初级程序员应能仅依靠 Home 和链接页面回答：
|
||
|
||
- 项目解决什么问题；
|
||
- 怎样启动和运行测试；
|
||
- 常用功能从哪个目录和入口开始读；
|
||
- 一个简单修改通常要改哪里、验证什么；
|
||
- 哪些情况必须停止并交给 Agent 或负责人；
|
||
- 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发；
|
||
- 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么；
|
||
- 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布；
|
||
- 跨子项目共享什么接口或契约，其唯一事实来源在哪里；
|
||
- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。
|
||
|
||
回答不了的问题应继续补充主题文档，而不是堆入任务归档。
|