diff --git a/New-Project-Documentation-Setup.-.md b/New-Project-Documentation-Setup.-.md new file mode 100644 index 0000000..5d994f5 --- /dev/null +++ b/New-Project-Documentation-Setup.-.md @@ -0,0 +1,125 @@ +# 新项目文档初始化 + +## 本页用途 + +从 DevHarness 创建新项目时,指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版,不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。 + +## 初始化顺序 + +### 1. 建立项目边界 + +由项目负责人确认: + +- 项目名称和一句话目标; +- 用户和主要使用场景; +- 技术栈和支持环境; +- Gitea 仓库、默认分支和维护者; +- 安全、权限、数据和发布红线。 + +把项目专用红线写入根目录或子目录 `AGENTS.md`。 + +### 2. 识别子项目与交付单元 + +先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认: + +- 职责和目录边界; +- 技术栈、依赖和支持环境; +- 构建、测试和运行命令; +- 是否拥有独立版本号和发布方式; +- 适用的根目录或子目录 `AGENTS.md`; +- 与其他子项目共享的接口、数据或业务流程; +- 共享契约的唯一事实来源和兼容要求。 + +把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元;多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`,但不因为技术栈不同自动拆仓,也不强制统一版本和发布周期。 + +### 3. 建立 Gitea + +创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。 + +### 4. 修改镜像配置 + +把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目;核心主题映射保留。 + +确认当前目录确实是新项目副本、且 DevHarness 历史归档不需要保留后,移除属于 DevHarness 的任务归档映射和对应 `docs/task/` 镜像。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。 + +不要把 PAT 写入配置。 + +### 5. Agent 检查项目事实 + +Agent 只读检查: + +- README、配置和依赖文件; +- 启动入口; +- 主要模块和目录规则; +- 测试、格式和静态检查命令; +- 日志、示例配置和测试数据; +- 已存在的接口、数据模型和状态。 + +区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。 + +### 6. 确定交付对象和文档 + +由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品,并为每类对象确定: + +- 需要完成的工作; +- 所需文档类型; +- 文档可见范围; +- 适用版本、负责人和验证人; +- 不得对外披露的内部信息。 + +按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档,使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建,不预建空白的用户手册、管理员手册或运维手册。 + +### 7. 先创建线上 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 给出建议阅读顺序;每个命令必须有预期结果;代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。 + +### 8. 人工确认 + +项目负责人至少确认: + +- 一句话目标和业务术语; +- 关键业务规则和状态; +- 权限、安全和数据边界; +- 真实运行、测试和部署命令; +- 哪些修改属于高风险; +- 交付对象、文档可见范围和外部信息边界。 + +### 9. 导出镜像并检查 + +```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/`。旧项目的任务归档不能带入新项目历史。 + +## 完成标准 + +初级程序员应能仅依靠 Home 和链接页面回答: + +- 项目解决什么问题; +- 怎样启动和运行测试; +- 常用功能从哪个目录和入口开始读; +- 一个简单修改通常要改哪里、验证什么; +- 哪些情况必须停止并交给 Agent 或负责人; +- 项目包含哪些子项目和独立交付单元,各自怎样构建、测试和发布; +- 跨子项目共享什么接口或契约,其唯一事实来源在哪里; +- 项目需要向哪些岗位交付什么文档,以及哪些内容不能对外提供。 + +回答不了的问题应继续补充主题文档,而不是堆入任务归档。