From eadd91170b87e442dc37a614d082e7a1e128bc32 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Fri, 27 Mar 2026 10:12:24 +0800 Subject: [PATCH] docs: refine agent coordination guidance --- CLAUDE.md | 66 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 55 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 737f187..51f7d8e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,42 @@ # CLAUDE.md -本文件用于指导 Claude Code 在本仓库中的工作方式。 +本文件用于指导 Claude Code 及通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。 + +## Workspace Coordination + +本仓库现在是 `water-workspace` 下的文档总控仓，默认作为正式规格、计划、任务、验收与治理台账的单一入口。 + +### 邻接仓库 + +- `../water-backend/`：后端实现仓，默认主开发分支为 `develop` +- `../water-frontend/`：前端实现仓，默认主开发分支为 `develop` + +### 启动规则 + +- 需要运行 `/speckit.specify`、`/speckit.plan`、`/speckit.tasks`、正式文档修订、治理台账更新、验收结论汇总时，必须从 `water-docs` 根目录启动代理。 +- 需要检查正式规格、计划、任务、基线、evidence 时，以 `water-docs/specs/` 与 `water-docs/docs/` 为准。 +- 未经用户明确要求，不在本仓库直接修改 `../water-backend/` 或 `../water-frontend/` 中的业务代码。 + +### 多仓协作规则 + +- 本仓库中的 `.specify/` 是唯一正式流程入口，backend/frontend 不复制第二套 `.specify/`。 +- backend/frontend 仓内实现结论，必须回写到本仓库的正式文档或 `specs/` 工件，不能仅停留在代码仓口头说明。 +- 重要 feature 默认记录代码基线： + - backend commit SHA + - frontend commit SHA + - 验证日期 + +### Worktree 约定 + +- 推荐在 `../worktrees/` 下按 feature 建立平铺 worktree： + - `docs-` + - `backend-` + - `frontend-` + - `verify-` +- 文档 lane 只改 `water-docs` +- backend lane 只改 `water-backend` +- frontend lane 只改 `water-frontend` +- verify lane 负责样本、日志、验收结论和基线固定 ## 项目定位 @@ -20,14 +56,17 @@ ```text / ├── docs/design/00_Management/ # 项目管理、进度跟踪、交付规范、编写指南 -├── docs/design/01_Overview/ # 总体设计：系统概述、系统架构、概要设计、系统图谱 -├── docs/design/02_Detailed_Design/ # 详细设计：主详设、模块设计、CA 安装设计 -├── docs/design/03_Technical_Design/ # 技术专项：数据库、表结构、接口、安全、部署、加密 -├── docs/design/04_Appendix/ # 附录与归档资料 -├── assets/ # 图片、模板等静态资源 -├── docs/ # 研究资料、映射文档、使用指南 -├── scripts/ # 文档处理与导出脚本 -└── infra/ # 辅助基础设施 +├── docs/design/01_Overview/ # 总体设计：系统概述、系统架构、概要设计、系统图谱 +├── docs/design/02_Detailed_Design/ # 详细设计：主详设、模块设计、CA 安装设计 +├── docs/design/03_Technical_Design/ # 技术专项：数据库、表结构、接口、安全、部署、加密 +├── docs/design/04_Appendix/ # 附录与归档资料 +├── .claude/ # Claude Code 相关配置 +├── .omc/ # 项目记忆与代理状态 +├── .zed/ # Zed 项目配置 +├── assets/ # 图片、模板等静态资源 +├── docs/ # 研究资料、映射文档、使用指南 +├── scripts/ # 文档处理与导出脚本 +└── infra/ # 辅助基础设施 ``` ## 当前文档组织原则 @@ -193,6 +232,9 @@ make export-word make export-pdf make export-html make unified-export +npm run check:marksman +npm run marksman:help +npm run marksman:server ``` 如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。 @@ -256,11 +298,13 @@ make unified-export - 归档整理与信息整编助手 - 基于现有资料进行保守补完的编辑者 -不是： +而不是： - 擅自扩展需求的产品经理 - 无依据发明实现细节的方案生成器 -- 动辄新建文件的“版本制造机” +- 动辄新建文件的”版本制造机” + +本文件用于指导通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。 ## 最终目标