2026-08-08 09:00:44 +08:00
|
|
|
|
<!-- 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.-
|
2026-08-10 14:25:34 +08:00
|
|
|
|
wiki_revision: 710503a62b7a4ebd3c9d7a1a08dbd398161595d0
|
|
|
|
|
|
synchronized_at: 2026-08-10T06:23:35Z
|
2026-08-08 09:00:44 +08:00
|
|
|
|
<!-- gitea-wiki-mirror:end -->
|
|
|
|
|
|
|
|
|
|
|
|
# 新项目文档初始化
|
|
|
|
|
|
|
|
|
|
|
|
## 本页用途
|
|
|
|
|
|
|
|
|
|
|
|
从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。
|
|
|
|
|
|
|
|
|
|
|
|
## 初始化顺序
|
|
|
|
|
|
|
|
|
|
|
|
### 1. 建立项目边界
|
|
|
|
|
|
|
|
|
|
|
|
由项目负责人确认：
|
|
|
|
|
|
|
|
|
|
|
|
- 项目名称和一句话目标；
|
|
|
|
|
|
- 用户和主要使用场景；
|
|
|
|
|
|
- 技术栈和支持环境；
|
|
|
|
|
|
- Gitea 仓库、默认分支和维护者；
|
|
|
|
|
|
- 安全、权限、数据和发布红线。
|
|
|
|
|
|
|
|
|
|
|
|
把项目专用红线写入根目录或子目录 `AGENTS.md`。
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 建立 Gitea
|
|
|
|
|
|
|
|
|
|
|
|
创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。
|
|
|
|
|
|
|
|
|
|
|
|
### 3. 修改镜像配置
|
|
|
|
|
|
|
2026-08-08 09:01:56 +08:00
|
|
|
|
把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；核心主题映射保留。
|
|
|
|
|
|
|
|
|
|
|
|
确认当前目录确实是新项目副本、且 DevHarness 历史归档不需要保留后，移除属于 DevHarness 的任务归档映射和对应 `docs/task/` 镜像。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
|
|
|
|
|
不要把 PAT 写入配置。
|
|
|
|
|
|
|
|
|
|
|
|
### 4. Agent 检查项目事实
|
|
|
|
|
|
|
|
|
|
|
|
Agent 只读检查：
|
|
|
|
|
|
|
|
|
|
|
|
- README、配置和依赖文件；
|
|
|
|
|
|
- 启动入口；
|
|
|
|
|
|
- 主要模块和目录规则；
|
|
|
|
|
|
- 测试、格式和静态检查命令；
|
|
|
|
|
|
- 日志、示例配置和测试数据；
|
|
|
|
|
|
- 已存在的接口、数据模型和状态。
|
|
|
|
|
|
|
|
|
|
|
|
区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。
|
|
|
|
|
|
|
2026-08-10 14:25:34 +08:00
|
|
|
|
### 5. 确定交付对象和文档
|
|
|
|
|
|
|
|
|
|
|
|
由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定：
|
|
|
|
|
|
|
|
|
|
|
|
- 需要完成的工作；
|
|
|
|
|
|
- 所需文档类型；
|
|
|
|
|
|
- 文档可见范围；
|
|
|
|
|
|
- 适用版本、负责人和验证人；
|
|
|
|
|
|
- 不得对外披露的内部信息。
|
|
|
|
|
|
|
|
|
|
|
|
按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。
|
|
|
|
|
|
|
|
|
|
|
|
### 6. 先创建线上 Wiki
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
|
|
|
|
|
至少创建或填写：
|
|
|
|
|
|
|
|
|
|
|
|
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；
|
2026-08-10 14:25:34 +08:00
|
|
|
|
9. Delivery-Documentation-Guide；
|
|
|
|
|
|
10. Audience-Document-Template；
|
|
|
|
|
|
11. Task-Archive-Template。
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
2026-08-10 14:25:34 +08:00
|
|
|
|
Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
2026-08-10 14:25:34 +08:00
|
|
|
|
### 7. 人工确认
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
|
|
|
|
|
项目负责人至少确认：
|
|
|
|
|
|
|
|
|
|
|
|
- 一句话目标和业务术语；
|
|
|
|
|
|
- 关键业务规则和状态；
|
|
|
|
|
|
- 权限、安全和数据边界；
|
|
|
|
|
|
- 真实运行、测试和部署命令；
|
2026-08-10 14:25:34 +08:00
|
|
|
|
- 哪些修改属于高风险；
|
|
|
|
|
|
- 交付对象、文档可见范围和外部信息边界。
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
2026-08-10 14:25:34 +08:00
|
|
|
|
### 8. 导出镜像并检查
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
|
|
|
|
|
```powershell
|
2026-08-08 09:18:09 +08:00
|
|
|
|
python dev_scripts/sync_wiki_docs.py
|
|
|
|
|
|
python dev_scripts/check_harness.py --strict
|
|
|
|
|
|
python dev_scripts/sync_wiki_docs.py --check
|
2026-08-08 09:00:44 +08:00
|
|
|
|
python -m unittest discover -s tests -v
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
只有线上 Wiki 确认后才导出 `docs/`。旧项目的任务归档不能带入新项目历史。
|
|
|
|
|
|
|
|
|
|
|
|
## 完成标准
|
|
|
|
|
|
|
|
|
|
|
|
初级程序员应能仅依靠 Home 和链接页面回答：
|
|
|
|
|
|
|
|
|
|
|
|
- 项目解决什么问题；
|
|
|
|
|
|
- 怎样启动和运行测试；
|
|
|
|
|
|
- 常用功能从哪个目录和入口开始读；
|
|
|
|
|
|
- 一个简单修改通常要改哪里、验证什么；
|
2026-08-10 14:25:34 +08:00
|
|
|
|
- 哪些情况必须停止并交给 Agent 或负责人；
|
|
|
|
|
|
- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。
|
2026-08-08 09:00:44 +08:00
|
|
|
|
|
|
|
|
|
|
回答不了的问题应继续补充主题文档，而不是堆入任务归档。
|
