以下规范适用于当前仓库内的 coding agent 协作与交付流程。
- 在保证安全、可追踪的前提下推进任务，避免不必要的流程阻断。
- 保持与现有仓库结构、实现风格和工程习惯一致。
- 禁止直接向受保护分支提交或推送：
main/master/release/*。 - 每项开发任务应在独立分支实施，建议从最新主干切出。
- 同步主干优先使用
git fetch+git merge --ff-only，避免隐式合并。 - 允许将开发分支推送到远端同名分支，便于协作与备份。
- 禁止改写公共历史：
git push --force、git push --force-with-lease、随意rebase。 - 仅提交本次任务相关文件，不清理或回滚与任务无关的在地改动。
- 开发类任务开始前，先检查是否已有相关 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 中同步，避免重复评论。
- 读写 Issue/PR 使用
ghCLI，不通过网页手工编辑。 - Issue、PR 与评论使用简体中文；专业术语可保留英文。
- 多行正文先写入临时文件，再用
--body-file传入；不要在--body中拼接\\n。 - 同仓引用使用
#123自动链接；跨仓引用使用完整 URL。
- 回归策略按改动类型选择；默认基线为：
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-commitmodifies files, include those changes in the same commit and rerunuv run pre-commit run --all-filesuntil it completes without further rewrites. - After running
pre-commit, inspectgit status --shortbefore 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-commitrun. - Shell/部署脚本改动：在基线之外，至少执行
bash -n对改动脚本做语法校验。 - 文档-only 改动：可不跑测试，但应自检命令与路径示例可用。
uv sync --all-extras仅在首次初始化或依赖变更时需要，不作为每次改动必做项。- 若受环境限制无法完成某项验证，必须在汇报中明确说明未执行项与原因。
- 严禁提交密钥、令牌、凭证或其他敏感信息（含
.env内容）。 - 日志与调试输出不得泄露访问令牌或隐私数据。
- 涉及部署、认证、密钥注入的改动，需同步更新文档并提供最小验收步骤。