AGENT SKILL

aria-commit

暂无简介

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

03 SKILL.md 正文

Git Commit Convention

Subject 说改了什么,正文说为什么。正文默认不写,说明一律英文。

本文件是仓库 commit 说明的规范(技能 aria-commit 的正文),AGENTS.md「Git 提交纪律」节为其摘要,细节以本文件为准。设计目标是一眼读完:多数提交只有一行标题,长内容归 .agents/reference/ 与 .agents/notes/ 等档案文档,commit 只当索引。说明用英文对齐主流规范(Conventional Commits 与 git 社区惯用的祈使句标题),也便于 git log --oneline 在任何终端与编码下稳定显示。本文件自身的中文叙述不受此限。

1. 形状

<type>(<scope>): <subject>

<optional body: 1-3 sentences of prose>

Tests: <optional single line>
段 必写 约束
Subject 是 祈使句、动词原形开头(add 不取 added)、小写开头、无句号;软目标 ≤ 50 列。72 列是整行上限(含 <type>(<scope>): 前缀),scope 长时得缩标题
Body 否 只在「标题与 diff 说不清 why」时写;1~3 句散文,≤ 4 行;不分段标签、不列 bullet;72 列折行
Tests: 行 否 跑过测试/构建就带一行结果;纯文档与脚本类可省;须是说明末行

语言纪律:说明一律英文且 ASCII-only--禁 CJK、全角标点、Unicode em-dash(破折号语义用 ASCII --);标识符、模块名、指令名原样引用(MAKE_METHOD、ObjString::load_index),不翻译。

2. type 与 scope

type 何时用
feat 行为从无到有(新特性 / 新机制 / 新 builtin)
fix 行为从错到对
refactor 外部可观测行为不变的结构调整
perf 行为不变,动机就是性能(测量报告按 aria-bench 处理)
docs 只改文档与注释
test 只改测试与语料基建(伴随 feat/fix 的测试随本批,不单拆)
build 构建系统与依赖
style 不改语义的格式化
chore 其余杂项(.gitignore、脚本、agent 配置)

scope 取仓库模块名(core / util / value / error / compile / bytecode / runtime / object / memory / tests / docs / build);跨模块逗号分隔、主模块在前、至多三个;全库性改动省略 scope。这是约定而非门禁:check_commit_msg.py 只校验 type 在九类内,不校验 scope。

3. 正文写什么

正文只回答标题与 diff 答不出的两件事:why,以及机制上不显然的那一点(跨文件因果、被否方案的结论)。这两点都写不出来,就不要正文。

禁写内容,判据一句话:这段文字描述的是本次改动,还是得到本次改动的过程--后者删掉,信息无损。

类别 反例 改法
实现步骤流水 "first added a method to ObjString, then moved it into util" 只写最终落点
评审/决策过程 "(user decision)"、"as discussed, we picked option B" 直述理由本身
被否方案推导 "deliberately not shared with the Lexer parser (which accepts _)" 一行结论或不写
实测数据 "extracting the helper measured 9% slower" 说明只写原因;配置阈值之类的行为常量可以保留
文档指针 "full rationale in some-plan.md" 删;文档随批提交,git show --stat 即可见
项目状态叙述 "there was previously nowhere to put this" 删;只写现在的行为与机制
规划词汇 "M5 phase 3"、"batch 9"、"finalize" 按语言域名称描述改动
空泛评价与完成体 "improve"、"clean up"、"fixed X" 说机制变化;动词用原形

4. 落笔(每次提交强制)

  1. 暂存后 git diff --cached --stat 核范围,只含本批文件。注意 git add -u 不收未跟踪文件--新增语料/测试/文档要先 git add <路径>,否则批次静默残缺且 --stat 不会提示。
  2. 说明写进临时文件(如 /tmp/commit_msg.txt),不用 -m 随手一句。
  3. python3 tools/check_commit_msg.py <file> 必须返回 0。两个坑:缺参数时它返 2(不是通过);以 Merge / Revert / fixup! / squash! 开头时它直接返 0(等于没查)。commit-msg 钩子会在落库时再跑一遍,但钩子是本地配置--新环境要先 git config core.hooksPath tools/hooks,否则静默不生效。
  4. git commit -F <file>;未推送时改说明用 git commit --amend -F <file>。
  5. git log -1 --format=%B 复读一遍。脚本拦截标题和正文格式错误;过程词、百分比、疑似哈希和日期等内容模式只提示。按 §3 复核它们在句中的作用,确认正文确实在解释本次改动的理由。

5. 粒度与流程

一个 commit 一个主题(一个特性 / 一个修复 / 一次重构 / 一轮文档收口),每批独立可编译、可 review、可回滚。与 review 流程咬合:改动完成 → 验证全绿 → 报告并停手 → 用户逐批 review → 点头后落一批 commit,一次 commit = 一次 review 通过的批。main 直推,保持线性历史,避免 merge commit。说明在落库时点当场写,不套用上一批的话术。

6. 例子

style(tests): drop decorative (void) casts
feat(runtime): add string to_int/to_float

Strings could only be converted out, so reading numeric data meant
hand-rolled parsing. Both methods parse the whole string in decimal via
util::parse_int_text/parse_float_text and return nil on failure; to_int
additionally gates the i48 domain.
Tests: ctest all green (default + TagValue); clang-format clean
fix(memory): iterate HashTable benchmark via const_iterator

The benchmark still called for_each_occupied after the slot-scan
primitive was retired, and that target is part of default ALL, so the
default build failed to compile.

反例与改法:

反例 错在哪
20 行 动机: / 改动:(三条 bullet)/ 验证: 三段骨架 标签与清单是模板声,改完只剩 2~4 行散文;读者要的是一眼读完
正文写 "deliberately not shared with the Lexer parser" + "measured 9% slower" + "full rationale in <doc>" 三段都是「得到本次改动的过程」,对「本批改了哪些代码」零信息
正文夹 "there was previously nowhere to put this" / "first added a method, then moved it" 叙述开发进程与实现步骤,读者要的是最终落点与理由
说明用中文或全角标点 与主流规范不一致,且 git log --oneline 在窄终端/异编码下不稳

7. 落笔前自检

  • [ ] 一批一主题,只含本批文件,type / scope 准确
  • [ ] Subject 是英文祈使句、动词原形、无句号、≤ 72 列
  • [ ] 正文 ≤ 4 行英文散文(无标签、无 bullet);没有过程叙述、被否推导、实测数字、文档指针、规划词汇
  • [ ] 全文 ASCII-only(无 CJK、全角标点、em-dash)
  • [ ] 写了 Tests: 就确实跑过,且结果与说明一致
  • [ ] 已按 §4 五步走过(脚本返回 0),并复读一遍全文

04 同仓库更多 Skills

deeplakee
deeplakee/aria-lang

aria-testing

写 aria 的 C++ GTest 用例或语言语料时使用。核对 CMake 登记、语料位置、期望文件与双配置验收;运行命令见 docs/testing.md,语料判定规则见 tests/language/README.md。

★ 1
deeplakee
deeplakee/aria-lang

aria-language-change

aria 语言面改动同步清单:改文法(docs/grammar.txt)、词法、语义或新增语言特性时使用。列出全部同步义务面:Parser/CodeGen 实现、tests/language 语料正负向、docs/guide 教程章节、README 特性表、.agents/reference 模块参考,及双配置全量验证要求。

★ 1
deeplakee
deeplakee/aria-lang

aria-error-messages

aria 报错文案规范速查:写或改任何面向用户的报错文案(编译期 / 运行期 / CLI / ASSERT)时使用。含 detail 通则、句式家族要点、元数族 arity_error 唯一口、被调者泛称、ASSERT 文案规则与机械门禁 tools/check_error_messages.py 的实际覆盖面。规范本体在 .agents/reference/specs/error-messages.md。

★ 1
deeplakee
deeplakee/aria-lang

aria-bytecode-change

加或改一条字节码指令(OpCode)时使用。列出完整同步面:code.hpp X 表追加与枚举序、dispatch_loop 的 case(漏 case 是运行期 fatal)、opcode_profile 的平行 switch 与 size_of/records_fall_pair、反汇编渲染与 kOpCodeCount 哨兵、CodeGen/CodeUnit 发射侧、instruction-set.md 与 lowering.md、语料与画像。

★ 1
deeplakee
deeplakee/aria-lang

aria-bench

aria 性能测量纪律:跑基准、做 A/B 对比、写性能报告时使用。含三层分工(bench/lang 进程级墙钟与跨语言对照、lexer/vm/hashtable 进程内微基准、bench/profile 指令频度画像)、各自的构建配方与目录、A/B 对照方法与报告规范、构建旗(ARIA_USE_TAGVALUE / ARIA_USE_MIMALLOC / ARIA_OPCODE_PROFILE)。

★ 1
deeplakee
deeplakee/aria-lang

aria-add-builtin

给 aria 加内建方法、静态原语或新内建类时使用。列出完整同步面:方法体与方法表、make_class 注册口(实例方法 vs 不绑定的静态原语)、receiver<T> 与 obj_tag 守卫、arity_error 元数口、返回值写槽与 GC 根、语料与文档(含 docs/guide/17-builtin-reference.md)。

★ 1