# project-spec

**Repository Path**: Fortuitous/project-spec

## Basic Information

- **Project Name**: project-spec
- **Description**: 项目开发规范仓库——沉淀通用工程规范（编码/提交/测试/安全/构建/评审/变更记录）与 CI/AI 协作约定，供各项目复用以保持规范一致。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# project-spec — 项目开发规范仓库

> 沉淀通用工程规范与 AI 协作约定，供各项目复用以保持规范一致。
> 主指导文件为 [`CLAUDE.md`](./CLAUDE.md)，细化子规范见 [`rules/`](./.agents/rules/README.md)，产品与技术文档模板见 [`docs/product/`](./docs/product/)，架构决策记录见 [`docs/adr/`](./docs/adr/)。英文简介见 [`README.en.md`](./README.en.md)。

## 目录结构

```
.
├── CLAUDE.md          # 主指导文件：语言要求 / 沟通风格 / 核心速查 / 规范触发时机 / 工作准则
├── README.md          # 本说明文档（使用 / 开发 / 维护指引）
├── CONTRIBUTING.md    # 贡献指南（如何为本仓库做贡献）
├── LICENSE            # 开源许可证（MIT）
├── .agents/           # AI 代理配置（工程规范，工具自动识别）
│   └── rules/         # 分层子规范（与 CLAUDE.md 同等约束力，冲突时以 rules 为准）
│       ├── README.md      # rules 索引与新增规范规则
│       ├── coding-spec.md # 编码：命名 / 类型安全 / 函数 / 注释 / 错误处理 / 性能
│       ├── commit-spec.md # 提交：Conventional Commits / Git Flow / PR 描述 / AI 署名
│       ├── test-spec.md   # 测试：命名 / 覆盖 / 就近 / 先写复现
│       ├── security-spec.md # 安全：密钥 / 注入 / 脱敏 / 依赖 / 误提交响应
│       ├── build-spec.md  # 验证：tsc / lint / test 门槛 + i18n
│       ├── review-spec.md # 评审：Self-audit 流程 + 严重性分级 + 检查单
│       ├── logging-spec.md # 记录：CHANGELOG / SemVer / 技术债管理
│       ├── release-spec.md # 发版：固化 CHANGELOG / tag 命名 / 发版闭环
│       ├── i18n-spec.md     # 文案 / 国际化：key 管理 / 翻译纪律 / 错误提示 / 护栏
│       ├── ui-spec.md       # UI：语义令牌 / 组件复用 / 分层 / 交互流程 / UX / 可访问性
│       ├── structure-spec.md # 目录结构：标准顶层布局 / docs / scripts / .agents / 迁移纪律
│       └── hooks-spec.md    # Hooks：Git 钩子自动化 + 前端自定义 hooks 规范与常用实现
│   └── mcp.json       # MCP 服务器配置模板（数据库 / 浏览器 / 代码平台 / 文档检索 / 工具，密钥 {env:VAR} 占位）
├── docs/              # 项目 / 产品 / 技术文档与模板
│   ├── product/       # 产品与技术文档模板（接入项目后按需复制填写）
│   │   ├── solution.md    # 技术方案 + 架构决策 + 可选内嵌技术债表
│   │   ├── features.md    # 产品需求 PRD 模板
│   │   ├── roadmap.md     # 开发计划 / 版本交付模板
│   │   ├── api.md         # 接口文档模板
│   │   └── TECH-DEBT.md   # 独立技术债清单（或内嵌于 solution.md，二选一）
│   └── adr/           # 架构决策记录（ADR）模板与索引
│       ├── README.md
│       └── ADR-0000.md    # ADR 模板示例
├── .githooks/         # Git 钩子（提交前验证 / 提交信息校验 / 推送前卫生，可选）
│   ├── README.md          # 启用说明与钩子清单
│   ├── lib.sh             # 公共函数库（颜色 / npm script 解析 / SKIP 跳过）
│   ├── pre-commit         # 提交前自动跑 build-spec 验证门槛
│   ├── commit-msg         # 校验 Conventional Commits 格式
│   └── pre-push           # 推送前敏感文件卫生检查
└── scripts/           # 维护脚本（如链接一致性检查）
    └── check-links.sh     # 校验所有 Markdown 相对链接
```

## 这个仓库是什么

一套**通用、技术栈无关**的工程开发规范，用于：

- **统一团队 / 个人多项目的开发节奏**：命名、类型、提交、测试、安全、构建门槛、评审、变更记录、发版。
- **约束 AI 编码代理**（Claude Code / OpenCode 等）：通过 `CLAUDE.md` + `.agents/rules/` 让代理遵循同样的规范。
- **沉淀最佳实践**：规范集中维护、一处更新、多项目生效。
- **提供文档骨架**：`docs/product/`（技术方案 / PRD / 计划 / 接口）与 `docs/adr/`（架构决策）模板，新项目可直接复制填充。

## 开始使用 / 克隆与二次开发

### 克隆仓库

```bash
# HTTPS（通用）
git clone https://gitee.com/Fortuitous/project-spec.git
# SSH（已配置 Gitee SSH Key 时）
git clone git@gitee.com:Fortuitous/project-spec.git
# 仅拉取最新规范（无需历史，常用于接入新项目）
git clone --depth 1 https://gitee.com/Fortuitous/project-spec.git
```

进入目录后，直接阅读 [`CLAUDE.md`](./CLAUDE.md) 与 [`rules/`](./.agents/rules/README.md) 即可开始使用。

### 二次开发（定制 / 扩展这套规范）

拿到这套规范后，常见两种二次开发路径：

#### 路径 A：基于本仓库 fork，维护你自己的规范分支

适合**你想长期维护一套定制规范**的场景：

```bash
# 方式一：Gitee 网页上 Fork 本仓库，再克隆你自己的副本
git clone https://gitee.com/<你的账号>/project-spec.git
cd project-spec

# 方式二：直接用本仓库新建分支 / 派生（如果你有写权限）
git checkout -b my-project
# ... 修改 .agents/rules/*.md、CLAUDE.md 后提交推送
git push origin my-project
```

改完即可在你自己项目里接入这套定制规范（见下方「快速开始」）。

#### 路径 B：克隆后本地化定制，用于你自己的项目

适合**不想维护独立仓库，只想借用这套规范**的场景：

```bash
git clone https://gitee.com/Fortuitous/project-spec.git my-specs
cd my-specs
# 按需裁剪 / 改写：
# - 精简 .agents/rules/ 下不需要的 spec
# - 修改 CLAUDE.md 的「语言要求 / 沟通风格」使其贴合你的协作习惯
# - 依据技术栈改写 .agents/rules/build-spec.md 的验证命令
# - 为项目追加专属规范（如该项目的特殊约束、命名约定）
```

然后按「快速开始 — 接入新项目」把这套定制规范复制进你的项目即可。

### 二次开发注意事项

- **保持通用性**：这套规范本身技术栈无关；你的专属条款建议单独成篇（如 `.agents/rules/my-spec.md`），不要污染通用 spec。
- **与上游同步**（fork 场景）：想跟上原仓库更新，可 `git remote add upstream https://gitee.com/Fortuitous/project-spec.git`，定期 `git fetch upstream` 合并。
- **冲突处理**：你项目专属规范与本套规范冲突时，以项目专属规范为准，并尽量回馈 / 说明差异。

## 快速开始 —— 如何接入一个新项目

### 方式一：直接复制（简单）

1. 克隆本仓库，将 `CLAUDE.md` 与 `.agents/rules/` 复制到目标项目根目录。
2. 依据目标项目技术栈，裁剪 `.agents/rules/build-spec.md` 中的验证命令（如改为目标项目的类型检查 / lint / 测试命令）。
3. 让 AI 代理加载规则：启动代理时它会自动读取项目根目录的 `CLAUDE.md` 与 `.agents/rules/`。
4. 遵循 [`CLAUDE.md`](./CLAUDE.md) 的「规范触发时机」表即可。

### 方式二：作为子模块 / 子目录引用（便于跟随更新）

```bash
# 在目标项目内引用本仓库（浅克隆到 .specs 或其他目录）
git clone --depth 1 --branch master https://gitee.com/Fortuitous/project-spec.git .specs
# 在目标项目的 CLAUDE.md / AGENTS.md 中用相对链接指向 .specs/CLAUDE.md 与 .specs/.agents/rules/
```

### 接入检查清单

- [ ] `CLAUDE.md` 中「语言要求」「沟通风格」与项目现状一致
- [ ] `.agents/rules/build-spec.md` 验证命令已换成项目实际命令
- [ ] `.agents/rules/**` 与目标项目技术栈无冲突（项目特有规范可覆盖，规范冲突以项目为准）
- [ ] AI 代理启动时能读到 `CLAUDE.md` 与 `.agents/rules/`

## 如何在项目里按这套规范开发

拿到规范后，日常开发遵循以下节奏：

1. **写代码前**：了解项目结构与已有风格，保持命名 / 类型 / 函数规范一致（见 [coding-spec](.agents/rules/coding-spec.md)）。
2. **切分支**：遵循 Git Flow——`master` 为发布分支，功能从 `develop` 切出特性分支，完成后合回（见 [commit-spec](.agents/rules/commit-spec.md)）。
3. **写 / 改测试**：就近放置、命名 `方法名_场景_期望结果`、先写复现用例（见 [test-spec](.agents/rules/test-spec.md)）。
4. **提交前必跑**：类型检查 + lint + 单测全绿，再走 Self-audit 检查单（见 [build-spec](.agents/rules/build-spec.md) + [review-spec](.agents/rules/review-spec.md)）。
5. **提交**：Conventional Commits，描述语言遵循项目约定（通用模板示例为中文；本项目自身用英文），原子化提交，AI 辅助代码标注署名（见 [commit-spec](.agents/rules/commit-spec.md)）。
6. **变更落地后必记**：更新 CHANGELOG（Keep a Changelog + SemVer），技术债入清单（见 [logging-spec](.agents/rules/logging-spec.md)）。
7. **全程安全**：密钥走环境变量、输入校验、日志脱敏（见 [security-spec](.agents/rules/security-spec.md)）。

> 一句话记忆：**提交前 build + review，提交后 logging**；编码看 coding，提交看 commit。

## 本仓库自身的做法（与通用模板的区别）

本项目规范是**通用模板**，接入项目时按实际裁剪；而**本仓库自己**作为规范母本，采用一套简化约定，二者关系如下：

| 维度 | 通用模板（接入项目） | 本仓库自身 |
|------|--------------------|-----------|
| 分支模型 | 完整 Git Flow（`main`/`develop`/`feature`/`release`/`hotfix`） | 简化：仅 `master` 单分支，改动直接提交 `master` |
| 提交语言 | commit-spec 示例多用中文描述 | **英文** Conventional Commits（如 `feat(spec): ...`） |
| 验证门槛 | 类型检查 + lint + 单测（见 build-spec） | 纯文档仓库，无构建；提交前 `git diff` 自查即可 |

> 说明：之所以这样，「通用模板」面向各技术栈项目需完整纪律；「本仓库自身」是纯 Markdown 文档，多分支与构建门槛无实际收益，刻意从简，避免形式大于内容。AI 辅助提交同样在信息末尾标注署名。

## 如何维护 / 演进这套规范

当你想修改或新增规范：

1. **改规范流程**：直接编辑对应 `rules/*.md` 或 `CLAUDE.md`，遵守「新增规范文档的规则」（见 [rules/README.md](.agents/rules/README.md)）。
2. **新增规范**：在 `.agents/rules/` 下新建 `kebab-case.md`（顶部注明适用范围），并在 `CLAUDE.md` 的「核心速查 / 触发时机表」补充引用链接。
3. **冲突处理**：`.agents/rules/` 文档为准，冲突时尽快修正另一方。
4. **本仓库提交**：同样遵循本套规范 —— 英文 Conventional Commits、提交前无需 build（纯文档）、提交记录 CHANGELOG。

### 维护建议

- 规范仓库本身不绑定具体技术栈，尽量保持**通用**；确需技术栈特有的条目，单独成篇而非塞进通用 spec。
- 每次改动规范后，在 `CHANGELOG.md` 记录变更点，方便各项目追踪升级。
- 定期审视：若某条规范造成多处返工，考虑放宽或拆分。

## 本地运行 / 环境

- 本仓库为**纯文档仓库**，无构建与运行依赖，clone 后即可直接阅读 / 修改。
- 查看文档：任意 Markdown 阅读器；`.agents/rules/README.md` 是子规范索引。
- 提交验证：`git diff` 自查 + 英文 Conventional Commits 即可。
- 二次开发：纯 Markdown 编辑，无需安装任何开发工具链。

## 分层说明

- **主文件** 只保留高频交互基础（语言、沟通）+ 核心速查 + 触发时机表，避免臃肿。
- **子规范** 承载可执行细则，按主题拆分、可独立演进，新增规范统一入 `.agents/rules/`。