From a37f10d24243f0868bfa26033ef9a35d0d354fed Mon Sep 17 00:00:00 2001 From: tian <11429339@qq.com> Date: Wed, 10 Jun 2026 15:27:17 +0800 Subject: [PATCH] =?UTF-8?q?=E9=99=8D=E7=BA=A7verify=E7=9B=AE=E5=BD=95?= =?UTF-8?q?=EF=BC=8Cskills=E7=9B=AE=E5=BD=95=E4=B8=BA=E5=8F=AF=E9=80=89?= =?UTF-8?q?=EF=BC=8C=E4=BF=AE=E6=94=B9=E4=B8=80=E4=BA=9B=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E8=A6=81=E6=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md => AGENTS.md | 0 README.md | 24 ++++++++++++------- data/index.md | 17 +++++++++++++ docs/implementation/index.md | 2 ++ docs/index.md | 18 ++++++++------ docs/requirements/index.md | 2 ++ {verify => docs/verify}/checklist/index.md | 0 docs/verify/index.md | 20 ++++++++++++++++ skills/index.md | 14 ++++------- src/index.md | 28 ++++------------------ verify/index.md | 22 ----------------- 11 files changed, 78 insertions(+), 69 deletions(-) rename CLAUDE.md => AGENTS.md (100%) create mode 100644 data/index.md rename {verify => docs/verify}/checklist/index.md (100%) create mode 100644 docs/verify/index.md delete mode 100644 verify/index.md diff --git a/CLAUDE.md b/AGENTS.md similarity index 100% rename from CLAUDE.md rename to AGENTS.md diff --git a/README.md b/README.md index 164a1d4..0891c7a 100644 --- a/README.md +++ b/README.md @@ -11,25 +11,33 @@ ├── LICENSE # 许可证 ├── CONTRIBUTING.md # 贡献规范 ├── .gitignore # Git 忽略规则 -├── CLAUDE.md # AI 编码助手上下文 +├── AGENTS.md # AI 编码助手上下文 │ -├── src/ # 源代码 +├── src/ # 源代码（所有业务模块） +├── data/ # 项目数据（知识库源、SQL dump 等非代码数据） ├── test/ # 测试代码 │ ├── unit/ # 单元测试 │ ├── integration/ # 集成测试 │ └── e2e/ # 端到端测试 │ ├── docs/ # 开发文档 -│ ├── requirements/ # 需求与变更管理 │ ├── design/ # 设计方案（架构 + 技术方案） +│ │ ├── architecture/ # 架构设计 & ADR +│ │ └── technical/ # 技术方案 / 详细设计 │ ├── features/ # 功能规格说明 -│ └── implementation/ # 实施计划与任务跟踪 +│ ├── requirements/ # 需求与变更管理（可选） +│ ├── implementation/ # 实施计划与任务跟踪（可选） +│ └── verify/ # 人工检查清单（可选） │ -├── skills/ # AI 辅助技能 +├── skills/ # AI 辅助技能（pi 专用，可选） ├── scripts/ # 构建、部署、工具脚本 -└── verify/ # 验证、检查清单、上线验收 +└── config/ # 项目级配置文件（非代码） ``` +> - **可选目录**：已有 Jira/TAPD 等工单系统的团队可删除 `requirements/` 和 `implementation/`；不用 pi 编码助手的可删除 `skills/` +> - **`src/` vs 根目录**：业务代码放 `src/`，入口文件（`app.py`、`main.go`）和配置文件（`pytest.ini`、`ruff.toml`、`.env.example`）留根目录 +> - **`data/` vs `test/fixtures/`**：`data/` 放项目级数据（知识库源文件等），`test/fixtures/` 放测试专用 fixture 数据 + ## 快速开始 ```bash @@ -45,9 +53,9 @@ cd | 你想做的事 | 去哪看 | |------------|--------| | 了解项目背景和架构 | `docs/design/architecture/` | -| 查看需求与变更 | `docs/requirements/` | +| 查看需求与变更 | `docs/requirements/`（可选） | | 查看功能设计 | `docs/features/` | -| 查看任务进度 | `docs/implementation/tasks/` | +| 查看任务进度 | `docs/implementation/tasks/`（可选） | | 参与开发 | `CONTRIBUTING.md` | | 查看版本历史 | `CHANGELOG.md` | diff --git a/data/index.md b/data/index.md new file mode 100644 index 0000000..1e00671 --- /dev/null +++ b/data/index.md @@ -0,0 +1,17 @@ +# data — 项目数据 + +本目录存放非代码的项目数据文件，区别于源代码和文档。 + +## 用途 + +- 初始化/种子数据 +- 数据库导出快照（用于参考或迁移） +- 静态数据文件（如地理信息、字典数据等） +- 其他非代码的静态项目数据 + +## 原则 + +1. 不含可执行代码或业务配置文件 +2. 文件应可被版本控制追踪（大文件请使用 Git LFS） +3. 按数据类型或用途建立子目录 +4. 与 `test/fixtures/` 区分：`data/` 放项目级数据，`test/fixtures/` 放测试专用数据 diff --git a/docs/implementation/index.md b/docs/implementation/index.md index 02ce7d9..e6f504f 100644 --- a/docs/implementation/index.md +++ b/docs/implementation/index.md @@ -1,5 +1,7 @@ # docs/implementation — 实施与跟踪 +> **可选**：如果团队已使用 Jira/TAPD/飞书等工单系统管理任务，可直接删除此目录。 + 本目录用于管理开发实施计划和任务进度。 ## 目录结构 diff --git a/docs/index.md b/docs/index.md index f1ccbac..51f22b6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,19 @@ # docs — 开发文档 -本目录存放项目的全部开发文档，涵盖需求、设计、功能规格和实施跟踪。 +本目录存放项目的全部开发文档，涵盖需求、设计、功能规格、实施跟踪和质量验证。 ## 目录说明 -| 子目录 | 用途 | 受众 | -|--------|------|------| -| `requirements/` | 需求与变更管理 | 产品、开发、测试 | -| `design/` | 架构设计与技术方案 | 开发、架构师 | -| `features/` | 功能规格说明 | 开发、测试、产品 | -| `implementation/` | 实施计划与任务跟踪 | 开发、项目管理 | +| 子目录 | 用途 | 受众 | 必选 | +|--------|------|------|:--:| +| `requirements/` | 需求与变更管理 | 产品、开发、测试 | 可选 | +| `design/` | 架构设计与技术方案 | 开发、架构师 | ✅ | +| `features/` | 功能规格说明 | 开发、测试、产品 | ✅ | +| `implementation/` | 实施计划与任务跟踪 | 开发、项目管理 | 可选 | +| `verify/` | 人工检查清单（上线/代码审查/安全审计） | 开发、运维 | 可选 | + +> - 标记"可选"的目录：如果团队已使用 Jira/TAPD/飞书等工单系统管理需求和任务，可直接删除，避免双写不同步。 +> - `verify/` 与 `test/` 的区别：`test/` 是**自动化代码测试**，`verify/` 是**人工检查清单和验证流程**。 ## 使用原则 diff --git a/docs/requirements/index.md b/docs/requirements/index.md index b32595b..47f5291 100644 --- a/docs/requirements/index.md +++ b/docs/requirements/index.md @@ -1,5 +1,7 @@ # docs/requirements — 需求与变更管理 +> **可选**：如果团队已使用 Jira/TAPD/飞书等工单系统，可直接删除此目录，避免双写。 + 本目录用于管理项目需求及其变更记录。 ## 目录结构 diff --git a/verify/checklist/index.md b/docs/verify/checklist/index.md similarity index 100% rename from verify/checklist/index.md rename to docs/verify/checklist/index.md diff --git a/docs/verify/index.md b/docs/verify/index.md new file mode 100644 index 0000000..7812299 --- /dev/null +++ b/docs/verify/index.md @@ -0,0 +1,20 @@ +# verify — 验证与质量保障 + +本目录存放人工检查清单和验证流程文档。 + +> 已从顶层目录迁移至 `docs/verify/`，以下为历史兼容说明。**新项目请直接使用 `docs/verify/`**。 + +## 目录结构 + +``` +verify/ +├── index.md # 本文件 +└── checklist/ # 检查清单 +``` + +## 用途 + +- 上线前检查清单 +- 发布验收清单 +- 代码审查清单 +- 安全审计清单 diff --git a/skills/index.md b/skills/index.md index ebdef53..2adb49a 100644 --- a/skills/index.md +++ b/skills/index.md @@ -1,17 +1,13 @@ # skills — AI 辅助技能 -本目录用于存放项目专属的 AI 辅助技能 / 提示词，帮助 AI 编码助手更好地理解项目上下文。 +本目录存放 AI 编码助手的辅助技能定义（遵循 [Agent Skills 标准](https://agentskills.io)）。 -## 用途 - -- 项目特定的编码规范和约定 -- 代码审查清单 -- 自动化提示词（如：生成测试、生成文档等） +> **注意**：本目录仅适用于使用 pi 编码助手或兼容 Agent Skills 标准的工具。[其他工具可删除此目录。] ## 使用方式 -将自定义的提示词文件放入本目录，并按需要引用。 +在对话中通过 `/skill:技能名` 调用，或由 AI 自动加载。 ---- +## 现有技能 -> 当前为空，可根据团队需要添加。 +当前尚无自定义技能。 diff --git a/src/index.md b/src/index.md index 042dcde..cc693a1 100644 --- a/src/index.md +++ b/src/index.md @@ -1,27 +1,9 @@ # src — 源代码 -本目录存放项目的全部源代码。 +本目录存放项目的全部业务源代码。 -## 组织原则 +## 原则 -- 按模块/功能划分子目录，避免扁平结构过于庞大 -- 公共组件、工具函数独立成目录或模块 -- 保持目录层级不超过 3-4 层 - -## 推荐结构 - -``` -src/ -├── core/ # 核心业务逻辑 -├── utils/ # 通用工具函数 -├── models/ # 数据模型 / 实体 -├── services/ # 服务层（如有） -├── api/ # API 接口层（如有） -└── main.* # 入口文件 -``` - -## 注意事项 - -- 该结构为建议，请根据项目实际技术栈和框架调整 -- 保持模块间低耦合、高内聚 -- 公共代码优先放在 `utils/` 或独立模块中 +1. 所有 Python/Go/Java 等业务模块统一收入 `src/` 下 +2. 根目录仅保留入口文件（如 `app.py`、`main.go`）、配置文件和文档 +3. 按功能模块建立子目录，保持扁平层次（不超过 3 层为宜） diff --git a/verify/index.md b/verify/index.md deleted file mode 100644 index 90d984d..0000000 --- a/verify/index.md +++ /dev/null @@ -1,22 +0,0 @@ -# verify — 验证与质量保障 - -本目录存放与质量验证相关的文档和检查清单。 - -## 目录结构 - -``` -verify/ -├── README.md # 本文件 -└── checklist/ # 检查清单 -``` - -## 用途 - -- 上线前检查清单 -- 发布验收清单 -- 代码审查清单 -- 安全审计清单 - ---- - -> 与 `test/` 的区别：`test/` 是**自动化代码测试**，`verify/` 是**人工检查清单和验证流程**。