降级verify目录，skills目录为可选，修改一些文件要求
This commit is contained in:
parent
aca7dc999e
commit
a37f10d242
24
README.md
24
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 <project-name>
|
||||
| 你想做的事 | 去哪看 |
|
||||
|------------|--------|
|
||||
| 了解项目背景和架构 | `docs/design/architecture/` |
|
||||
| 查看需求与变更 | `docs/requirements/` |
|
||||
| 查看需求与变更 | `docs/requirements/`（可选） |
|
||||
| 查看功能设计 | `docs/features/` |
|
||||
| 查看任务进度 | `docs/implementation/tasks/` |
|
||||
| 查看任务进度 | `docs/implementation/tasks/`（可选） |
|
||||
| 参与开发 | `CONTRIBUTING.md` |
|
||||
| 查看版本历史 | `CHANGELOG.md` |
|
||||
|
||||
|
||||
17
data/index.md
Normal file
17
data/index.md
Normal file
@ -0,0 +1,17 @@
|
||||
# data — 项目数据
|
||||
|
||||
本目录存放非代码的项目数据文件，区别于源代码和文档。
|
||||
|
||||
## 用途
|
||||
|
||||
- 初始化/种子数据
|
||||
- 数据库导出快照（用于参考或迁移）
|
||||
- 静态数据文件（如地理信息、字典数据等）
|
||||
- 其他非代码的静态项目数据
|
||||
|
||||
## 原则
|
||||
|
||||
1. 不含可执行代码或业务配置文件
|
||||
2. 文件应可被版本控制追踪（大文件请使用 Git LFS）
|
||||
3. 按数据类型或用途建立子目录
|
||||
4. 与 `test/fixtures/` 区分：`data/` 放项目级数据，`test/fixtures/` 放测试专用数据
|
||||
@ -1,5 +1,7 @@
|
||||
# docs/implementation — 实施与跟踪
|
||||
|
||||
> **可选**：如果团队已使用 Jira/TAPD/飞书等工单系统管理任务，可直接删除此目录。
|
||||
|
||||
本目录用于管理开发实施计划和任务进度。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@ -1,15 +1,19 @@
|
||||
# docs — 开发文档
|
||||
|
||||
本目录存放项目的全部开发文档，涵盖需求、设计、功能规格和实施跟踪。
|
||||
本目录存放项目的全部开发文档，涵盖需求、设计、功能规格、实施跟踪和质量验证。
|
||||
|
||||
## 目录说明
|
||||
|
||||
| 子目录 | 用途 | 受众 |
|
||||
|--------|------|------|
|
||||
| `requirements/` | 需求与变更管理 | 产品、开发、测试 |
|
||||
| `design/` | 架构设计与技术方案 | 开发、架构师 |
|
||||
| `features/` | 功能规格说明 | 开发、测试、产品 |
|
||||
| `implementation/` | 实施计划与任务跟踪 | 开发、项目管理 |
|
||||
| 子目录 | 用途 | 受众 | 必选 |
|
||||
|--------|------|------|:--:|
|
||||
| `requirements/` | 需求与变更管理 | 产品、开发、测试 | 可选 |
|
||||
| `design/` | 架构设计与技术方案 | 开发、架构师 | ✅ |
|
||||
| `features/` | 功能规格说明 | 开发、测试、产品 | ✅ |
|
||||
| `implementation/` | 实施计划与任务跟踪 | 开发、项目管理 | 可选 |
|
||||
| `verify/` | 人工检查清单（上线/代码审查/安全审计） | 开发、运维 | 可选 |
|
||||
|
||||
> - 标记"可选"的目录：如果团队已使用 Jira/TAPD/飞书等工单系统管理需求和任务，可直接删除，避免双写不同步。
|
||||
> - `verify/` 与 `test/` 的区别：`test/` 是**自动化代码测试**，`verify/` 是**人工检查清单和验证流程**。
|
||||
|
||||
## 使用原则
|
||||
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# docs/requirements — 需求与变更管理
|
||||
|
||||
> **可选**：如果团队已使用 Jira/TAPD/飞书等工单系统，可直接删除此目录，避免双写。
|
||||
|
||||
本目录用于管理项目需求及其变更记录。
|
||||
|
||||
## 目录结构
|
||||
|
||||
20
docs/verify/index.md
Normal file
20
docs/verify/index.md
Normal file
@ -0,0 +1,20 @@
|
||||
# verify — 验证与质量保障
|
||||
|
||||
本目录存放人工检查清单和验证流程文档。
|
||||
|
||||
> 已从顶层目录迁移至 `docs/verify/`，以下为历史兼容说明。**新项目请直接使用 `docs/verify/`**。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
verify/
|
||||
├── index.md # 本文件
|
||||
└── checklist/ # 检查清单
|
||||
```
|
||||
|
||||
## 用途
|
||||
|
||||
- 上线前检查清单
|
||||
- 发布验收清单
|
||||
- 代码审查清单
|
||||
- 安全审计清单
|
||||
@ -1,17 +1,13 @@
|
||||
# skills — AI 辅助技能
|
||||
|
||||
本目录用于存放项目专属的 AI 辅助技能 / 提示词，帮助 AI 编码助手更好地理解项目上下文。
|
||||
本目录存放 AI 编码助手的辅助技能定义（遵循 [Agent Skills 标准](https://agentskills.io)）。
|
||||
|
||||
## 用途
|
||||
|
||||
- 项目特定的编码规范和约定
|
||||
- 代码审查清单
|
||||
- 自动化提示词（如：生成测试、生成文档等）
|
||||
> **注意**：本目录仅适用于使用 pi 编码助手或兼容 Agent Skills 标准的工具。[其他工具可删除此目录。]
|
||||
|
||||
## 使用方式
|
||||
|
||||
将自定义的提示词文件放入本目录，并按需要引用。
|
||||
在对话中通过 `/skill:技能名` 调用，或由 AI 自动加载。
|
||||
|
||||
---
|
||||
## 现有技能
|
||||
|
||||
> 当前为空，可根据团队需要添加。
|
||||
当前尚无自定义技能。
|
||||
|
||||
28
src/index.md
28
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 层为宜）
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
# verify — 验证与质量保障
|
||||
|
||||
本目录存放与质量验证相关的文档和检查清单。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
verify/
|
||||
├── README.md # 本文件
|
||||
└── checklist/ # 检查清单
|
||||
```
|
||||
|
||||
## 用途
|
||||
|
||||
- 上线前检查清单
|
||||
- 发布验收清单
|
||||
- 代码审查清单
|
||||
- 安全审计清单
|
||||
|
||||
---
|
||||
|
||||
> 与 `test/` 的区别：`test/` 是**自动化代码测试**，`verify/` 是**人工检查清单和验证流程**。
|
||||
Loading…
Reference in New Issue
Block a user