From f30886e44226f1d6e2db056ccc19005240e2ab5a Mon Sep 17 00:00:00 2001 From: weichen Date: Sun, 13 Sep 2026 02:44:39 +0000 Subject: [PATCH] docs(agents): require feature branches off dev for all work Align AGENTS, Cursor rule, PROJECT, README, templates, and CURRENT with strategy A: no direct commits on dev/test/main; all work branches from dev. Co-authored-by: Cursor --- .../rules/git-workflow-and-environments.mdc | 10 ++--- .../reference/branch-and-environment-rules.md | 2 + .doc/ops/CURRENT.md | 10 ++--- .doc/ops/templates/session-close-checklist.md | 6 ++- .doc/ops/templates/short-term-task.md | 2 +- AGENTS.md | 40 ++++++++++++++----- PROJECT.md | 6 ++- README.md | 6 +-- 8 files changed, 54 insertions(+), 28 deletions(-) diff --git a/.cursor/rules/git-workflow-and-environments.mdc b/.cursor/rules/git-workflow-and-environments.mdc index 18c58135..59d6d4d0 100644 --- a/.cursor/rules/git-workflow-and-environments.mdc +++ b/.cursor/rules/git-workflow-and-environments.mdc @@ -10,18 +10,18 @@ alwaysApply: true ## 一、 Git 固定三分支体系 1. **开发分支 (`dev`)**: - - 所有代码日常开发在此分支进行。 - - 细小变更直接在 `dev` 上分批逐步提交。 - - 独立大功能可从 `dev` 检出子分支 `feature/` 或 `fix/`，在本地测试完成后合并回 `dev`（`--no-ff`），并删除临时子分支。 + - **合入基线**，不是日常 commit 目标。 + - **禁止**在 `dev` 上直接开发提交（含 docs/chore）。 + - 一律从最新 `dev` 检出 `feature/` 或 `fix/`，在 feature 分支上渐进式提交；自测后占集成槽位，`--no-ff` 合回 `dev`，并删除临时子分支（见 [AGENTS.md](../../AGENTS.md) §6.2）。 2. **测试分支 (`test`)**: - 当 `dev` 积累了一定的功能阶段后，合并至 `test` 分支，创建阶段候选节点 Tag（如 `rc-vX.Y.Z-beta.1`）。 - 用于较长时间的真实环境部署、全链路集成测试、运维稳定性检验。 - - 严禁在 `test` 分支进行未经规划的大规模功能开发。 + - **严禁**在 `test` 分支进行开发或直接 commit。 3. **主分支 (`main`)**: - 生产发布分支（Release）。 - - 严禁直接在 `main` 上开发！ + - **严禁**直接在 `main` 上开发或 commit！ - 只有 `test` 分支的代码经过实际运维和测试充分验证达到发布标准后，方可将对应验证节点合并回 `main` 分支，并打正式发布 Tag（如 `v1.0.0`）。 --- diff --git a/.doc/archive/reference/branch-and-environment-rules.md b/.doc/archive/reference/branch-and-environment-rules.md index 1bca88e0..269800f2 100644 --- a/.doc/archive/reference/branch-and-environment-rules.md +++ b/.doc/archive/reference/branch-and-environment-rules.md @@ -1,5 +1,7 @@ # 研发分支与多套独立环境运行规范 (Branch & Environment Rules) +> **HISTORICAL**：日常开发分支策略已由 [AGENTS.md](../../../AGENTS.md) §6.2、[PROJECT.md](../../../PROJECT.md) §4 与 [`.cursor/rules/git-workflow-and-environments.mdc`](../../../.cursor/rules/git-workflow-and-environments.mdc) 取代为「一律从 `dev` 开 `feature/*` 或 `fix/*`，禁止在三大主干直接 commit」。本文档保留作环境矩阵与历史流程参考。 + 本规范为本系统代码仓库的强制性规范，涵盖 **Git 3 分支流转模型**、**任务功能拆分与渐进式提交**、**三套环境独立运行（知识库共享 + 对话与数据库隔离）** 以及 **运维操作指引**。 --- diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 8f7c46d7..7b249fbf 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -1,13 +1,13 @@ # 当前焦点 **更新**: 2026-09-13 -**production_ready**: no（CI 真实 PI E2E + 前端人工抽检待完成） +**production_ready**: no（对话刷新恢复、CI 真实 PI E2E、前端人工抽检待完成） ## 焦点 -1. **CI**: `TEST_DATABASE_URL` + 真实 PI E2E 实录 -2. **前端**: 版本冲突刷新、终止 preview 人工抽检 -3. **BACKLOG**: session cookie / bundle 拆分 / 容量治理（见 [backlog](../backlog/chat-agent-p6-backlog.md)） +1. **CHAT**: [刷新恢复整改待实施](short-term/2026-09-13-chat-history-refresh-remediation.md)（发布 blocker） +2. **CI**: `TEST_DATABASE_URL` + 真实 PI E2E 实录 +3. **前端**: 版本冲突刷新、终止 preview 人工抽检 ## 并行认领 @@ -15,7 +15,7 @@ |-------|------|--------|----------|-------|--------| | — | — | — | — | — | — | -> 新任务开始前登记。同一 `mutex` 同时仅一个 `in_progress`。 +> 新任务开始前登记。`branch` 必须为 `feature/` 或 `fix/`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。 ## 集成槽位 diff --git a/.doc/ops/templates/session-close-checklist.md b/.doc/ops/templates/session-close-checklist.md index 7fe12942..ae2cb032 100644 --- a/.doc/ops/templates/session-close-checklist.md +++ b/.doc/ops/templates/session-close-checklist.md @@ -10,8 +10,10 @@ ## 代码与分支 -- [ ] 非 trivial 改动已 merge `--no-ff` 到 dev（或 handoff 说明未 merge 原因） -- [ ] 无未 push 的 dev 关键提交（若用户要求同步远端） +- [ ] 确认未在 `dev` / `test` / `main` 上直接 commit（工作均在 `feature/*` 或 `fix/*`） +- [ ] 已占集成槽位并 `merge --no-ff` 合回 `dev`（或 handoff 说明未 merge 原因） +- [ ] feature/fix 分支已删除或 worktree 已 remove（若已合入） +- [ ] 无未 push 的关键提交（若用户要求同步远端） ## 文档 diff --git a/.doc/ops/templates/short-term-task.md b/.doc/ops/templates/short-term-task.md index ac16f3ce..a1d7dbff 100644 --- a/.doc/ops/templates/short-term-task.md +++ b/.doc/ops/templates/short-term-task.md @@ -4,7 +4,7 @@ status: planned created: YYYY-MM-DD updated: YYYY-MM-DD owner: agent -branch: feature/ +branch: feature/ # 必填：feature/* 或 fix/*；禁止 dev / test / main worktree: "-" mutex: --- diff --git a/AGENTS.md b/AGENTS.md index 8bfdada6..e27aa717 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,17 +105,36 @@ **同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。 -### 6.2 分支与 Worktree +### 6.2 分支与 Worktree（策略 A：一律从 dev 开分支） -- 非 trivial 改动必须独立分支，禁止多人直推同一 dev 工作区抢改。 -- **多 Agent 并行时强制 worktree**：`.worktrees//`（已 gitignore） -- 脚本：`./scripts/agent-worktree.sh create|list|remove` +> **禁止**在 `dev` / `test` / `main` 三大主干上直接 `git commit`（含代码、配置、文档）。 +> `dev` 仅作合入点；`test`/`main` 仅作环境晋升合入，禁止开发。 -| Worktree 允许 | Worktree 禁止 | -|---------------|---------------| -| 编码、`go test -short ./...` | `env-service.sh * start/stop/restart` | +**任务开始（先于改码）：** + +1. 更新本地 `dev`：`git checkout dev && git pull`（若已配置远端） +2. 从 `dev` 创建分支：`feature/`（新能力）或 `fix/`（缺陷）；slug 与 short-term 任务名对齐 +3. 多 Agent 并行：用 `./scripts/agent-worktree.sh create feature/`（worktree 内编码） +4. 单 Agent：可在主仓 `git checkout -b feature/`，**不得**留在 `dev` 上改码提交 + +**合回 dev（占集成槽位，见 §6.3）：** + +```bash +git checkout dev +git merge --no-ff feature/ -m "merge: feature/" +# 冒烟通过后 +git branch -d feature/ # 或 agent-worktree.sh remove +``` + +| 允许 | 禁止 | +|------|------| +| 在 `feature/*` / `fix/*` 上 commit | 在 `dev` / `test` / `main` 上 commit | +| worktree 内 `go test -short ./...` | worktree 内 `env-service.sh * start/stop/restart` | +| 占槽后在主仓 merge 入 `dev` | 多人直推同一 `dev` 工作区抢改 | | 连主仓已起服务 `:8080` | 各 worktree 各起 docker | +脚本：`./scripts/agent-worktree.sh create|list|remove` + ### 6.3 集成槽位（合入 dev + 容器验证） > **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。** @@ -161,11 +180,12 @@ audit（问题）→ remediation（方案）→ ops/short-term（任务） ## 8. Git 与提交 - 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci` -- **原子提交**：一个逻辑变更一批 -- merge 回 dev 用 `--no-ff` +- **原子提交**：一个逻辑变更一批；提交发生在 `feature/*` 或 `fix/*` 上，不在三大主干 +- **合回 dev**：占集成槽位后 `merge --no-ff`（见 §6.2、§6.3） +- **晋升**：`dev` → `test`（rc tag）→ `main`（release tag）；仅在规划的环境合并时动 `test`/`main` - **用户未要求**：不擅自 push - **用户已要求 push/同步远端**：必须自主完成 -- **禁止**：在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时 +- **禁止**：在 `dev`/`test`/`main` 上直接开发 commit；在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时 --- diff --git a/PROJECT.md b/PROJECT.md index 88b4e005..5c840aa0 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -52,6 +52,8 @@ **红线**：知识库共享；对话与业务 DB **严格隔离**，禁止跨环境读写。 +**分支红线**：三大主干（`dev`/`test`/`main`）禁止直接开发 commit；一律从 `dev` 开 `feature/*` 或 `fix/*`，合回 `dev` 须占集成槽位（见 [AGENTS.md](./AGENTS.md) §6）。 + --- ## 5. 文档地图（SSOT） @@ -124,11 +126,11 @@ cd web && npm test && npm run build - 发布缺口 SSOT：[gap-matrix](./.doc/remediation/gap-matrix.md) - 模块完成度：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md) - 最新测试报告：[2026-09-13-codex-audit-p0-remediation-test-report.md](./.doc/test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md) -- **剩余 blocker**: CI 真实 PI E2E + 前端人工抽检（main 本地冒烟已通过） +- **剩余 blocker**: 对话刷新恢复与历史读取授权一致性 + CI 真实 PI E2E + 前端人工抽检（main 本地冒烟已通过） --- ## 10. 语言与提交 - 对用户：**简体中文** -- 提交：Conventional Commits；在 `dev` 上渐进式分批提交 +- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，合回 `dev` 用 `--no-ff`（禁止在三大主干直接 commit） diff --git a/README.md b/README.md index 332380fd..6c45a01f 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ | 分支名 | 定位 | 职责与准入规则 | | :--- | :--- | :--- | -| **`dev`** | **开发分支** | **日常开发基线**。所有代码开发均在此分支或其衍生子分支（`feature/*`, `fix/*`）进行，子分支自测后合并回 `dev`。支持一个任务按功能拆解并逐步渐进式提交。 | -| **`test`** | **测试分支** | **准生产实测分支**。当 `dev` 积累了一定功能阶段后合并至此，建立发布候选节点（`rc-vX.Y.Z`），进行真实环境部署与长期集成测试与运维检验。 | -| **`main`** | **主分支** | **生产发布分支**。严禁直接提交。仅在 `test` 分支经过真实运维和测试验证达到发布标准后，将对应节点合并回 `main` 并打正式版本 Tag（`vX.Y.Z`）。 | +| **`dev`** | **开发合入基线** | 禁止直接 commit。从最新 `dev` 开 `feature/*` 或 `fix/*` 开发，自测后占集成槽位 `--no-ff` 合回 `dev`。 | +| **`test`** | **测试分支** | 准生产实测；`dev` 阶段合并 + rc tag。**严禁**在此分支开发或 commit。 | +| **`main`** | **主分支** | 生产发布；仅 `test` 验证通过后合并。**严禁**直接开发或 commit。 | 完整的分支流转模型、热修复流程与提交规范请参阅：[PROJECT.md](./PROJECT.md) §4（SSOT）。