ilaandClaude Fable 5
0184595ccc
Harness governance / validate (push) Has been cancelled
Initialize the full harness coding document set from the harness_coding_docs template, customized for the SoftBox project: - Vision, requirements, tech stack (modern Go 1.25 + Gio v0.10.1; Win7 legacy Go 1.20.14 + Gio v0.6.0), architecture, coding rules - Protocol contracts (signed catalog, package protocol v1, Ed25519 license, events, CLI) and Gio view structure - Roadmap Phase 0-6 with 20 suggested tasks; T-001 (monorepo skeleton) filed and ready to claim - Agent entry points (AGENTS.md, docs/00-ai-start-here.md), context manifest, governance scripts and tests - Merge Go gitignore with harness rules; keep go.work tracked Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
71 lines
4.7 KiB
Markdown
71 lines
4.7 KiB
Markdown
# 已有项目接入清单
|
||
|
||
> 用于把本模板补进一个已经存在的项目。目标是先建立 agent 可读的事实来源，再继续开发新功能。
|
||
|
||
## 适用场景
|
||
|
||
- 项目已经有代码，但缺少清晰的 agent 入口、任务文件、当前状态和验证路径。
|
||
- 项目被多轮 AI 修改过，文档、代码和真实可运行状态已经不一致。
|
||
- 想从“靠聊天记录推进”切换到“靠仓库内工件推进”。
|
||
|
||
如果是全新空项目，优先按根目录 `README.md` 的“空项目接入”流程复制模板。
|
||
|
||
## 最小接入文件
|
||
|
||
先复制或建立这些文件：
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `AGENTS.md` | 仓库级 agent 入口和总规则 |
|
||
| `CLAUDE.md` | Claude Code 薄入口，指向 `AGENTS.md` |
|
||
| `docs/00-ai-start-here.md` | 每轮开工流程 |
|
||
| `docs/agent-context.json` | 按任务类型选择本轮上下文 |
|
||
| `docs/agent-context.schema.json` | 上下文清单结构契约 |
|
||
| `docs/agent-context.md` | 清单读取、缓存和断连降级规则 |
|
||
| `docs/05-coding-rules.md` | 编码纪律和验证底线 |
|
||
| `docs/06-tasks.md` | 任务路线图（阶段、里程碑、待办池） |
|
||
| `docs/tasks/` | 默认任务管理：一任务一文件（`README.md` + `_template.md`） |
|
||
| `docs/current-state.md` | 当前实现状态快照 |
|
||
| `init.sh` 或 `init.ps1` | 标准启动与验证入口，按操作系统二选一 |
|
||
| `scripts/validate_agent_context.py` | 零第三方依赖校验清单和引用路径 |
|
||
|
||
推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。
|
||
|
||
需要 Gitea 多 Agent 协作时，再复制 `docs/gitea-mcp.md`、`docs/gitea-collaboration.md`、`.gitea/` 模板、`scripts/setup_gitea_labels.py`、`scripts/audit_gitea_coordination.py`、离线治理脚本和测试；先只读预览远端标签差异，再由维护者显式 `--apply`。Actions 工作流仅在仓库已启用 Actions 且 runner 可用时生效。
|
||
|
||
## 接入步骤
|
||
|
||
1. 确认仓库根目录，读取已有 `README`、运行脚本、测试配置和主要入口文件。
|
||
2. 复制最小接入文件，把所有 `【占位符】` 替换成当前项目事实，并按项目任务类型调整 `agent-context.json` 的路由。
|
||
3. 在 `docs/current-state.md` 写清真实目录、真实启动命令、真实验证命令、当前 blocker。
|
||
4. 在 `docs/03-tech-stack.md` 固定已经实际使用的技术栈，不确定项标为“待定”，不要让 agent 自行选择。
|
||
5. 在 `docs/04-architecture.md` 记录当前代码的真实模块边界；不清楚的地方标为“待确认”。
|
||
6. 在 `docs/06-tasks.md` 只放下一阶段能小步交付的建议任务，不要把历史愿望清单全部搬进去；第一轮任务按 `docs/tasks/README.md` 落成 `docs/tasks/T-<编号>.md`。
|
||
7. 配置 `init.sh` 或 `init.ps1` 顶部三个命令，让它能安装依赖、运行基础验证、打印启动命令。
|
||
8. 运行 `python scripts/validate_agent_context.py` 和项目标准验证；如果失败，第一轮任务应先修基线，不做新功能。
|
||
9. 把接入过程、验证结果写进第一轮任务文件的 `## 执行记录`，遗留 blocker 同步到 `docs/current-state.md`。
|
||
|
||
## 第一轮 agent 任务建议
|
||
|
||
已有项目接入后的第一轮，不建议直接做新功能。推荐任务是：
|
||
|
||
| ID | 任务 | 验收要点 |
|
||
| --- | --- | --- |
|
||
| T-000 | 建立当前状态基线 | `current-state.md` 写清真实状态；`init` 脚本已配置；基础验证结果已记录到本任务文件的 `## 执行记录` |
|
||
| T-001 | 修复启动 / 验证基线 | 标准启动路径和标准验证路径可运行；失败原因已消除或记录为 blocker |
|
||
| T-002 | 对齐任务路线图 | `06-tasks.md` 只保留可小步交付的建议任务；第一个待落地任务依赖清楚、验收可观察 |
|
||
|
||
## 代码现实与文档冲突时
|
||
|
||
- 以当前可运行代码和真实验证结果为事实起点。
|
||
- 文档描述旧功能但代码不存在时，先把差异记录到 `current-state.md`，不要直接补实现。
|
||
- 代码已有行为但文档没写时，先补 `02-requirements.md`、`04-architecture.md` 或 `api.md`，再继续修改代码。
|
||
- 命令不可运行时，不要标记任务完成；在当前任务文件的 `## 执行记录` 记录失败命令和错误摘要。
|
||
|
||
## 不建议做的事
|
||
|
||
- 不要一次性把所有模板都填满；先让入口、当前状态、任务和验证路径可用。
|
||
- 不要把聊天记录当事实来源。
|
||
- 不要为了让验证通过而降低测试或验收标准。
|
||
- 不要在接入 harness 的同一轮顺手重构业务代码，除非是修复启动或验证基线所必需。
|