Development — 开发流程与约束

本页是根 README.md 的开发拆分页，汇总分支模型、质量门禁、提交规范与任务包工作流。 远程操作与分支约束的唯一事实源为 .trae/rules/remote-ops.md，以其为准；本页仅作导读。

一、分支三段流

text

cursor/<descriptive-name>   ──PR──►   ai_develop   ──PR(波次)──►   develop   ──人工 merge──►   main
        （AI 可写）         （CI 跑）   （AI 开发基线）  （CI 跑 + 门禁）           （不跑 CI，人工）

写权限：AI Agent 只能写 ai_develop 与 cursor/<descriptive-name> 分支。
合并方向：cursor/* → ai_develop（任务包完成）→ develop（一个波次完成）→ main（人工 merge）。
禁止：任何 main / develop 直接写操作、git push --force、跨分支 rebase / cherry-pick、自动建删分支、自动 merge PR。
创建 PR 时：base_branch 必须为 ai_develop（即使平台默认 main 也要主动覆盖）。例外仅限 cursor/align-* 与 cursor/sync-* 手术分支，且需用户明确指示。

该规则由 .github/workflows/branch-flow-guard.yml 在 PR 触发时做软校验（视觉警示，不硬阻挡）。

二、质量门禁

CI（.github/workflows/ci.yml）运行下列核心 job，本地等价命令：

bash

make lint           # ruff check
make format-check   # ruff format --check
make typecheck      # mypy app --strict
make importlinter   # lint-imports（架构依赖方向）
make test           # pytest（unit + integration + e2e）
make verify         # 脚手架 + 版本自检

门禁基线：pytest 全绿 · coverage ≥ 80% · mypy strict 无错误 · ruff check + format 无错误 · import-linter 合约通过。

编码规范（命名 / 注释 / D-H Facade / 测试）事实源：development_standard.md。

三、提交规范

Conventional Commits：feat: / fix: / chore: / docs: / refactor: / test: …
粒度：每个逻辑变更一个 commit；禁止 amend / force push。
凭据：任何 token / 私钥 / 真实值不得入库；.env.example 仅放 key + 注释。

四、任务包工作流（PROMPT / TASK / TDD 三件套）

业务代码变更不要随手改，需走任务包流程：

在 docs/design/3.task/packages/ 下由编排器基于 _template/ 生成具体任务包。
标准执行流程 PLAN → TDD → REVIEW → VERIFY 四步，每步启动全新子 Agent 会话，经 stage-lock 串行流转。
阶段锁：.plan_done → .tdd_done → .review_done → .done（.done = 任务整体完成，下游可启动）。

方法论与门禁详见 docs/design/3.task/README.md 与 task_orchestration.md。

五、远程 / 测试机操作

只允许走白名单脚本，严禁裸 ssh ecs-b "..." 跑业务命令：

脚本	用途
`scripts/deploy-from-cloud-agent.sh`	Cloud Agent VM → ECS-B 的唯一部署入口
`scripts/deploy-to-testbed.sh`	本地人工部署入口
`scripts/verify-testbed.sh`	测试机健康验证
`scripts/logs-testbed.sh`	测试机日志拉取

六、FROZEN 文档与新依赖

FROZEN：architecture-scaffold.md / tech_stack.md / development_standard.md 及 ADR-0001~0018 已冻结，变更需新增 ADR。
新依赖：禁止先斩后奏，须经 ADR 评审并同步升级 tech_stack.md。
vendor / artifacts / generated：视为只读，不修改。

七、相关页

环境与运行 → getting-started.md
架构总览 → architecture.md
仓库结构 → project-structure.md
远程操作事实源 → .trae/rules/remote-ops.md

Development — 开发流程与约束 ​

一、分支三段流 ​

二、质量门禁 ​

三、提交规范 ​

四、任务包工作流（PROMPT / TASK / TDD 三件套） ​

五、远程 / 测试机操作 ​

六、FROZEN 文档与新依赖 ​

七、相关页 ​