# AGENTS.md

以下规范适用于当前仓库内的 coding agent 协作与交付流程。

## 1. 核心原则

- 在保证安全、可追踪的前提下推进任务，避免不必要的流程阻断。
- 保持与现有仓库结构、实现风格和工程习惯一致。

## 2. Git 工作流

- 禁止直接向受保护分支提交或推送：`main`/`master`/`release/*`。
- 每项开发任务应在独立分支实施，建议从最新主干切出。
- 同步主干优先使用 `git fetch` + `git merge --ff-only`，避免隐式合并。
- 允许将开发分支推送到远端同名分支，便于协作与备份。
- 禁止改写公共历史：`git push --force`、`git push --force-with-lease`、随意 `rebase`。
- 仅提交本次任务相关文件，不清理或回滚与任务无关的在地改动。

## 3. Issue 与 PR 协作

- 开发类任务开始前，先检查是否已有相关 open Issue（例如 `gh issue list --state open`）。
- 若无相关 Issue，应创建新 Issue 跟踪；Issue 建议包含背景、复现步骤、预期/实际、验收标准，并附 `git rev-parse HEAD` 快照。
- 仅协作规范/流程文档改动（如 `AGENTS.md`）可直接修改，无需额外创建 Issue。
- Issue 标题前缀建议使用 `[feat]`、`[bug]`、`[docs]`、`[ops]`、`[chore]`。
- 提交信息若服务于某个 Issue，应在 commit message 中标注对应 `#issue`。
- PR 默认建议创建为 Draft，并在描述中标明关联关系（如 `Closes #xx` / `Relates to #xx`）。
- 出现关键进展、方案变化或新风险时，及时在对应 Issue/PR 中同步，避免重复评论。

## 4. 工具与文本规范

- 读写 Issue/PR 使用 `gh` CLI，不通过网页手工编辑。
- Issue、PR 与评论使用简体中文；专业术语可保留英文。
- 多行正文先写入临时文件，再用 `--body-file` 传入；不要在 `--body` 中拼接 `\\n`。
- 同仓引用使用 `#123` 自动链接；跨仓引用使用完整 URL。

## 5. 回归与验证

- 回归策略按改动类型选择；默认基线为：
  - `bash ./scripts/validate_baseline.sh`
- Before committing, complete the required validation for the current change set; by default, run the baseline checks above before creating a commit.
- Before creating or updating a PR, confirm the relevant local validation has passed so CI is not left to catch issues that are already reproducible locally.
- `pre-commit` 若自动修复文件（如 `ruff --fix`），需复查改动后再提交。
- If `pre-commit` modifies files, include those changes in the same commit and rerun `uv run pre-commit run --all-files` until it completes without further rewrites.
- After running `pre-commit`, inspect `git status --short` before committing or pushing; do not assume hook-made rewrites are already included in the pending commit.
- Do not push or update a PR while the working tree still contains hook-generated edits from the latest `pre-commit` run.
- Shell/部署脚本改动：在基线之外，至少执行 `bash -n` 对改动脚本做语法校验。
- 文档-only 改动：可不跑测试，但应自检命令与路径示例可用。
- `uv sync --all-extras` 仅在首次初始化或依赖变更时需要，不作为每次改动必做项。
- 若受环境限制无法完成某项验证，必须在汇报中明确说明未执行项与原因。

## 6. 安全与配置

- 严禁提交密钥、令牌、凭证或其他敏感信息（含 `.env` 内容）。
- 日志与调试输出不得泄露访问令牌或隐私数据。
- 涉及部署、认证、密钥注入的改动，需同步更新文档并提供最小验收步骤。
