# Git 工作流 — AI Agent 操作指南

> 把此文件粘贴给任何 AI Agent，让它了解本项目的 git 工作方式。由炼境接入包分发。
> `ONBOARDING_MANAGED` 标记块由炼境版本化管理（重跑接入包可原位升级），块外可自由补充项目特有约定。

<!-- ONBOARDING_MANAGED_START version="1.3.0" -->

## 分支策略

```
简单改动  → 直接 push main/master
功能改动  → feat/<name> 分支 → PR → main/master
```

- **简单改动**（单文件 bug 修复、配置调整、文档更新）：直接 push `main`/`master`
- **功能性改动**（多文件修改、新功能、重构、接口变更）：开 `feat/<功能简述>` 分支，完成后 PR 合入
- 不维护常设 `dev` 分支——每个改动按复杂度选路径，功能分支用完即关

> **为什么**：PR body 是意图层数据（炼境从中采集 Why + 验收结论），PR CI review 是 agent 自验链的最后一环；简单改动不值得开分支的额外成本——按实际复杂度决策，不一刀切。

## Commit 规范（lefthook 强制）

格式：`<type>(<scope>): <描述>`

| type | 用途 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `chore` | 配置、依赖、脚本 |
| `docs` | 文档 |
| `refactor` | 重构（不改功能） |
| `ci` | CI 配置 |
| `perf` | 性能优化 |
| `style` | 代码格式 |
| `test` | 测试 |

`scope` 用「模块/子模块」二级结构（如 `auth/login`、`api/user`、`db/order`），对应项目功能模块。

```bash
git commit -m "feat(auth/login): 新增手机号登录"
git commit -m "fix(api/user): 修正分页 off-by-one"
```

> 炼境会解析这些 commit 的 type/scope 作为飞轮数据：`fix` 计入返工率、`scope` 归到模块。
> **commit 写得越规范，飞轮数据越准。**

## Rules-Applied trailer（规则命中回传）

若本次任务中触发过 CONVENTIONS 自动推荐规则（R01-R11，见 `.blueprint/CONVENTIONS.md` 规则列表），
在 commit message 末尾追加一行 trailer（与正文空行分隔）：

```
feat(auth/login): 新增手机号登录

Rules-Applied: R01,R05
```

- 只记录**真实触发**（主动检查或执行）的规则，未触发则整行省略
- 炼境自动解析此 trailer 做「规则命中 × 返工」交叉统计，是 CONVENTIONS 置信度进化的数据来源
- 凭空罗列会污染数据——宁缺毋滥

## 一个 commit = 一件独立的事

不要 `git add -A` 一次提交所有。按功能分批：

```bash
git add <相关文件>
git commit -m "feat(模块): 一件事"
```

## PR 大小控制

PR 别攒太大（建议每 3~5 个 commit 或几百行内就开一次），否则 CI code review 易超时失效。
「所有检测通过」≠ 代码被审查过——大 PR 即使 CI 全绿，review 可能已静默失效。

## PR 创建（炼境托管项目）

本项目由炼境管理，MCP 已注入且 `.claude/liangjing.json` 含 `project_id`。

**推送分支后，通过炼境 MCP 创建 PR，禁止用 curl + git credential fill 提取 token：**

```
1. Read .claude/liangjing.json  →  取出 project_id
2. 调用 MCP 工具 create_pull_request：
   { "project_id": "<id>", "head": "feat/<name>", "base": "main",
     "title": "<Conventional Commits 格式>", "body": "<变更摘要>" }
3. 炼境内部用存储的 Gitea 凭证调 API，返回 pr_url
```

若炼境未运行（MCP 不可用），降级方案：去 Gitea 网页手动创建 PR。

## 常用命令

```bash
git status --short
git log --oneline -10
git reset --soft HEAD~1   # 撤销最后一次 commit（保留改动）
```
<!-- ONBOARDING_MANAGED_END -->