docs: 恢复分支开发模式 - AI 不切换分支,默认多AI协作,经验沉淀不标注AI身份
This commit is contained in:
SpecialX
@@ -246,13 +246,17 @@ services/[service]/src/
|
||||
|
||||
## 8. Git 工作流
|
||||
|
||||
- **分支策略**：trunk-based，直接提交到 `main` 分支（因 Gitea 问题，**不再使用特性分支/发布分支/hotfix 分支，不再使用 PR 流程**）
|
||||
- **提交方式**：所有变更直接 `git push origin main`；禁止 `git checkout -b` 创建任何分支
|
||||
- **提交前同步**：`git pull --rebase origin main` 拉取最新，解决冲突后再 push
|
||||
- **分支策略**：分支开发。**人类决策者手动维护分支**（创建分支、合并到 main），AI 不得自行切换/创建/合并分支
|
||||
- **AI 分支约束（强制）**：
|
||||
- AI 只在人类分配的当前分支上工作
|
||||
- **禁止** `git checkout -b`、`git switch`、`git branch` 创建或切换分支
|
||||
- **禁止** `git merge`、`git push origin main`（合并与推送 main 由人类负责）
|
||||
- AI 完成工作后 `git add` + `git commit` 提交到当前分支，通知人类合并
|
||||
- **提交前校验**：commit 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python）
|
||||
- **pre-commit hook**：`lint-staged` 自动修复 + 校验（见 `lint-staged.config.js`）
|
||||
- **commit-msg hook**：commitlint 校验格式
|
||||
- **禁止 force push**：除非显式要求并通知团队
|
||||
- **回滚**：`git revert <commit>` + `git push origin main`，不使用分支回滚
|
||||
- **回滚**：由人类在 main 上 `git revert <commit>`，不使用分支回滚
|
||||
- **默认多 AI 协作**：所有工作默认按多 AI 合作模式进行（见 §14），每个 AI 在各自分支独立工作
|
||||
|
||||
---
|
||||
|
||||
@@ -289,7 +293,9 @@ services/[service]/src/
|
||||
- **去重**：同类问题在原条目补充，不重复创建
|
||||
- **引用架构规则**：架构分层、模块结构等规则引用 004 和本规则文件，不重复
|
||||
- **只读自己模块分区**：AI 查阅 known-issues 时只读自己负责模块的分区，禁止读其他 AI 模块的分区（避免被历史记录误导）
|
||||
- **禁止流水日志**：known-issues 不再设"工作经验日志"区，不写跨模块流水账；模块内的经验沉淀在各自模块的 README/文档中
|
||||
- **禁止工作日志**：known-issues 不设"工作经验日志"区，不写流水账、不写"做了什么/学到什么"
|
||||
- **经验沉淀不标注 AI 身份**：所有经验记录只写"场景→技术/规则"映射，**不得出现 AI 标识（如 ai01/ai02/coord 等）**，避免新同名 AI 将前任记录误认为当前事实
|
||||
- **模块内经验**：模块内的经验沉淀在各自模块的 README/文档中，同样不标注 AI 身份
|
||||
|
||||
---
|
||||
|
||||
@@ -321,12 +327,12 @@ services/[service]/src/
|
||||
|
||||
### 阶段 3：经验沉淀（强制，不可跳过）
|
||||
|
||||
1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志）
|
||||
1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志，**不标注 AI 身份**）
|
||||
2. 若发现新的架构决策 → 更新 004
|
||||
3. 若代码结构变化 → `pnpm run arch:scan` 确认 arch.db 已更新
|
||||
4. 模块内的经验沉淀到**自己模块的 README/文档**，不污染全局 known-issues
|
||||
4. 模块内的经验沉淀到**自己模块的 README/文档**，不污染全局 known-issues，同样不标注 AI 身份
|
||||
|
||||
> **禁止**在 known-issues.md 写跨模块"工作经验日志/流水账"。known-issues 是索引式速查手册，只保留场景→技术映射。新 AI 不应被前任同名 AI 的流水记录误导。
|
||||
> **禁止**在 known-issues.md 写"工作经验日志/流水账"。known-issues 是索引式速查手册，只保留场景→技术映射，**不出现任何 AI 标识**。
|
||||
|
||||
---
|
||||
|
||||
@@ -377,18 +383,18 @@ services/[service]/src/
|
||||
|
||||
## 14. 多 AI 协作规范
|
||||
|
||||
> 详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。
|
||||
> **默认多 AI 协作**：所有 AI 工作默认按多 AI 合作模式进行。详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。
|
||||
|
||||
### 14.1 角色与权限
|
||||
|
||||
| 角色 | 职责 | 直接 push main | 修改他人模块 | force push main |
|
||||
| -------------------------- | ---------------------------------------- | -------------- | ----------------------------- | --------------- |
|
||||
| **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布 | ✅ | ✅（shared-proto/infra/docs） | ⚠️（仅事故） |
|
||||
| **开发 AI（Dev）** | 按模块分工写代码、直接 push main | ✅ | ❌ | ❌ |
|
||||
| **SRE AI** | `infra/` 维护、部署 | ✅（infra） | ✅（仅 infra） | ⚠️（仅事故） |
|
||||
| **人类决策者** | 架构决策、Breaking Change 审批、发布确认 | — | — | — |
|
||||
| 角色 | 职责 | 在分支提交 | 合并到 main | force push main |
|
||||
| -------------------------- | -------------------------------------------------------- | ----------- | ------------------------- | --------------- |
|
||||
| **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布 | ✅ | ❌（由人类合并） | ⚠️（仅事故） |
|
||||
| **开发 AI（Dev）** | 按模块分工写代码、在分支提交 | ✅ | ❌ | ❌ |
|
||||
| **SRE AI** | `infra/` 维护、部署 | ✅（infra） | ❌（由人类合并） | ⚠️（仅事故） |
|
||||
| **人类决策者** | 架构决策、分支管理、合并、Breaking Change 审批、发布确认 | — | ✅（手动合并分支到 main） | ⚠️（仅事故） |
|
||||
|
||||
> 不再使用特性分支与 PR。所有变更直接 `git push origin main`。代码审查改为事后追溯（通过 commit message + commit history），不在 push 前阻塞。
|
||||
> AI 在分配的分支上提交，**不自行合并到 main**。合并由人类决策者负责。
|
||||
|
||||
### 14.2 模块单一负责制与模块边界（强制）
|
||||
|
||||
@@ -399,17 +405,18 @@ services/[service]/src/
|
||||
- `shared-proto`、`shared-tokens`、`docs/` 由协调 AI 维护，开发 AI 只读引用
|
||||
- `infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
|
||||
|
||||
### 14.3 直接 push main 规则（强制）
|
||||
### 14.3 分支开发规则（强制）
|
||||
|
||||
1. **禁止创建分支**：不使用 `git checkout -b`、`git branch` 创建任何特性/发布/hotfix 分支
|
||||
2. **直接 push main**：所有变更 `git add` → `git commit` → `git pull --rebase origin main` → `git push origin main`
|
||||
3. **提交前校验**：push 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python）
|
||||
4. **提交信息规范**：遵循 Conventional Commits（见 §7），commit message 末尾标注 AI 身份（见 §14.6）
|
||||
5. **不阻塞审查**：push 不等待 review，问题通过事后 commit revert 或后续 commit 修正
|
||||
1. **分支由人类创建**：人类决策者为每个任务/模块创建分支并分配给 AI，AI 不得自行创建分支
|
||||
2. **AI 禁止切换分支**：AI 不得执行 `git checkout -b`、`git switch`、`git branch` 等分支创建/切换命令
|
||||
3. **AI 禁止合并/推送 main**：`git merge`、`git push origin main` 由人类决策者执行，AI 只提交到当前分支
|
||||
4. **AI 提交流程**：`git add <files>` → `git commit -m "<type>(<scope>): <subject>"` → 通知人类合并
|
||||
5. **提交前校验**：commit 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python）
|
||||
6. **提交信息规范**：遵循 Conventional Commits（见 §7）
|
||||
|
||||
### 14.4 跨模块变更顺序（强制）
|
||||
|
||||
修改涉及多模块时，按依赖顺序**依次直接 push main**（不拆 PR，按顺序提交避免下游编译失败）：
|
||||
修改涉及多模块时，按依赖顺序依次在各模块分支完成，由人类决策者按顺序合并到 main：
|
||||
|
||||
1. `shared-proto`（proto 契约）
|
||||
2. 业务服务（classes / iam / core-edu 等）
|
||||
@@ -417,26 +424,20 @@ services/[service]/src/
|
||||
4. BFF（teacher-bff 等）
|
||||
5. 微前端（teacher-portal 等）
|
||||
|
||||
> 每提交一层并 push 后，再开发下一层。协调 AI 负责监督顺序，避免越级提交导致下游构建失败。
|
||||
> 每合并一层到 main 后，再合并下一层。协调 AI 负责监督顺序，避免越级合并导致下游构建失败。
|
||||
|
||||
### 14.5 冲突处理规则
|
||||
|
||||
- **push 冲突**：`git pull --rebase origin main` 解决冲突后重新 `git push origin main`
|
||||
- **架构冲突**：由协调 AI 仲裁保留方案，通过 commit revert + 新 commit 修正
|
||||
- **分支冲突**：由人类决策者在合并时解决，或通知 AI 在分支上 `git rebase` 最新 main 后重新提交
|
||||
- **架构冲突**：由协调 AI 仲裁保留方案，通过新 commit 修正
|
||||
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `--force-with-lease`
|
||||
|
||||
### 14.6 AI 身份标注（强制）
|
||||
### 14.6 经验沉淀规则（强制）
|
||||
|
||||
每个 commit message body 末尾必须追加（用于追溯，不再有 PR 描述）：
|
||||
|
||||
```text
|
||||
---
|
||||
|
||||
AI-Agent: <ai-id> (<负责模块>)
|
||||
Coord: <协调 AI ai-id>
|
||||
```
|
||||
|
||||
> 不再有 Branch 字段（不使用分支）。每个 AI 的经验沉淀到自己模块的 README/文档，**禁止**在 known-issues.md 写跨模块工作日志。
|
||||
- **不记录工作日志**：AI 不在 known-issues.md 或任何文档中写"工作经验日志/流水账"
|
||||
- **只做经验沉淀**：遇到新的"场景→技术"映射，以索引式一行记录到 known-issues 对应模块分区
|
||||
- **不标注 AI 身份**：经验沉淀记录**不得出现 AI 标识**（如 ai01/ai02/coord 等），避免新同名 AI 误读
|
||||
- **模块内经验**：模块内的经验沉淀到各自服务 README/文档，同样不标注 AI 身份
|
||||
|
||||
### 14.7 敏感文件保护
|
||||
|
||||
@@ -469,14 +470,15 @@ Coord: <协调 AI ai-id>
|
||||
| **quality-proto** | ✅ | buf lint + buf breaking | 失败阻断 |
|
||||
| **deploy** | 串行 | docker compose up --build + 健康检查 | 失败阻断 |
|
||||
|
||||
> 不再使用 PR。所有质量检查与部署在 push main 时触发。
|
||||
> 质量检查在分支推送时触发，部署仅在合并到 main 时触发。
|
||||
|
||||
### 15.3 触发条件
|
||||
|
||||
| 事件 | 触发阶段 | 触发条件 |
|
||||
| ----------------- | ------------------------------------------------------- | -------------------------------- |
|
||||
| push 到 main | quality-ts + quality-go + quality-proto（并行）+ deploy | 每次 push main 自动 |
|
||||
| workflow_dispatch | 上述全部 + deploy | 手动触发，支持 `commit_sha` 回滚 |
|
||||
| 事件 | 触发阶段 | 触发条件 |
|
||||
| ----------------- | ----------------------------------------------- | -------------------------------- |
|
||||
| 分支 push / PR | quality-ts + quality-go + quality-proto（并行） | 分支推送自动 |
|
||||
| push 到 main | 上述全部 + deploy | 合并后自动 |
|
||||
| workflow_dispatch | 上述全部 + deploy | 手动触发，支持 `commit_sha` 回滚 |
|
||||
|
||||
> **不再支持 tag 发布**：no-push 模式下不用 `git tag v*` 触发。版本管理通过 commit SHA 追溯。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user