feat: agent friendly commits (#64)

* feat: agent friendly commits

* feat: agent friendly commits

Author: Charliechen114514

.claude/commands/audit.md

@@ -0,0 +1,35 @@
+---
+description: 对一篇文章跑「事实核查 + 严谨性」双审查并产出修正 —— 复用两个公开审查 prompt 的方法论
+argument-hint: "[必填: 待审查文章的相对/绝对路径]"
+---
+
+# /audit — 文章双审查(事实 + 严谨)
+
+你是**执行者**:对目标文章做两轮审查,**直接修改文章并产出报告**。
+
+## 输入
+
+`$ARGUMENTS` —— 待审查文章路径(必填)。为空则停下问用户要路径。
+
+## 方法论来源
+
+- **事实核查**:[`article-factcheck-audit.md`](../prompts/article-factcheck-audit.md)(人名 / 日期 / 规格 / 引用 / 代码声称行为)
+- **严谨性核查**:[`article-rigor-audit.md`](../prompts/article-rigor-audit.md)(无证据的"编译器会优化 / 更快"类断言)
+
+严格按这两个 prompt 的流程和约束执行,本命令只是把它们串成一次调用。
+
+## 流程
+
+1. **读全文**,通读目标文章。
+2. **事实轮**:标记需验证声明 → web search 查权威源 → 按 P0–P3 分级。
+3. **严谨轮**:标记无证据的技术 / 性能断言 → 编译验证(见硬约束)。
+4. **修正**:按 factcheck 的三要素(原文摘录 / RefLink / 验证路径)插入 `:::warning` / `:::details`;rigor 轮用真实汇编 / 输出替换空口描述。验证代码写入 `code/volumn_codes/vol{N}/`。
+5. **报告**:输出修正汇总表 + 新增引用 + 新增验证代码 + 验证清单。
+
+## 硬约束(行为纪律)
+
+- **编译只到 `/tmp/`**:`g++ -std=c++XX -O{0,2} -o /tmp/xxx /tmp/xxx.cpp`,运行 `/tmp/xxx` —— **分两次独立 Bash 调用,禁止 `&&` 串联**。
+- **禁止**在项目目录跑 cmake / make / ninja 或建 build 目录。
+- **禁止**把报告 / 日志写到 `/tmp/` 或任何位置 —— 报告直接作为返回文本输出。
+- 只修改目标文章 + 对应 `code/volumn_codes/` 目录。
+- 写作风格遵循 [`writing-style.md`](../style/writing-style.md)。

.claude/commands/explain.md

@@ -0,0 +1,28 @@
+---
+description: 给 C++ 学习者讲一个概念 —— 先在仓库定位项目怎么讲、再验证、用项目声音讲解(learning track 4 守则固化版)
+argument-hint: "[必填: 要讲解的 C++ 概念]"
+---
+
+# /explain — 给学习者讲一个 C++ 概念
+
+受众:懂 Agent、正在学 C++ 的人。你的任务是**当导师**,核心是**别让学习者绕弯**。严格按 [`learning-with-agents.md`](../../.github/learning-with-agents.md) 的四条守则。
+
+## 输入
+
+`$ARGUMENTS` —— 要讲解的概念(如 `memory_order_acquire`、`std::move`)。为空则停下问。
+
+## 流程(四守则)
+
+1. **定位**:先在**本仓库**找项目怎么讲这个概念 —— 查 `documents/roadmap/index.md`(学习顺序)和各卷 `documents/vol*/index.md`,grep 概念名,读项目已有处理。**别凭通用记忆现编一套**,对齐项目的讲法和进度。
+2. **验证**:凡涉及 C++ 行为断言,先编译实测或查 cppreference 标版本(做法同 `/verify-claim`)。**禁止凭记忆断言。**
+3. **讲解**:用**项目声音**讲([`writing-style.md`](../style/writing-style.md) Part 2)—— 讲"为什么"、类比 + 机制拆解、标志性句式、鼓励读者自己跑代码。
+4. **纠偏**:概念若有常见误解,主动点破(查 [`faq.md`](../../.github/faq.md))。
+
+## 输出
+
+一段项目风格的讲解 + 最小可编译代码(标 C++ 标准)+ 链接:项目对应文章 + cppreference。
+
+## 硬约束
+
+- 编译验证产物**只到 `/tmp/`**,不跑 cmake / make / build。
+- 讲解里的每条 C++ 行为都要能验证;不确定就说"我验一下"。

.claude/commands/minor.md

@@ -0,0 +1,59 @@
+---
+description: 讨论一轮 minor 发版打包 — 确认后产出【发版规划总结 + 稳定格式的迭代 Issue】到聊天框(只规划,不执行,不开 issue)
+argument-hint: "[可选: 本次发版框定/关注点,留空则由你扫描后建议]"
+---
+
+# /minor — 发版打包规划(规划者模式)
+
+你现在是**规划者**,不是执行者。本轮你**不修改任何文件、不建 tag、不碰版本号、不调 `gh`**。
+
+## 定位
+
+Minor = **发版打包规划**:把自上次 tag 以来累积的全部 patch(所有类型)捆成一次 release,讲清楚这次发版做了什么、到了哪个里程碑。
+
+**关键:内容推进本身是 patch 级工作**(每写一段内容都是一个 patch)。minor **不做内容**,只在"攒够了、要发版"时由用户**手工判定**触发,与 patch 类型无关。
+
+## 输入
+
+`$ARGUMENTS` —— 本次发版的框定或关注点。为空时由你扫描后给出建议。
+
+## 流程
+
+### 1. 扫描累积与路线
+
+- **累积 patch**: 运行
+  `git log $(git describe --tags --abbrev=0)..HEAD --oneline`
+  列出自上次 tag 以来的全部待打包提交。
+- **路线对照**: 读 `todo/000-project-roadmap.md` + 相关 `todo/01x-vol*.md`,看这批 patch 合起来推进了哪条 next-step。
+- ⚠️ 项目 Python 脚本一律用 `.venv/bin/python`。
+
+### 2. 框定本次发版
+
+- 把累积 patch 按类型粗分,给出本次 release 的**一句话叙事**。
+- 对照 volume TODO,说清本次发版**到达了哪个内容里程碑**。推进是 patch 做的,minor 只负责"看清楚到了哪"。
+- 若离更完整的 minor 还差一点:建议再补哪 1-2 个 patch(留给后续 `/patch`,不在 minor 里执行)。
+- **保持灵活,不搞死板**:讲明白发版范围即可,不强制验收标准、不强制文件清单。
+
+### 3. 提案 → 讨论 → 确认(核心是讨论)
+
+- 先用**一句话**讲清这次发版要打包什么,作为讨论起点(累积统计、里程碑口头带过,**别堆列表**)。
+- 与用户**来回讨论打磨**,直到用户**明确确认**。
+- **未确认前,不产出 Issue。**
+
+### 4. 确认后,产出两样东西到聊天框(讨论的最终产物)
+
+**(a) 本轮确认的发版工作** —— 一句话总结聊定的发版范围与里程碑。
+
+**(b) 迭代 Issue(Markdown)** —— 套用 `.claude/templates/iteration-issue.md`(极简版),迭代类型填 minor。用 ` ```markdown ` 代码块包裹。用户微调后**自行**送 GitHub。
+
+★ **(a)(b) 都必须通俗易懂**:用大白话写,少术语、别堆结构化清单,让没参与讨论的人也能一眼看懂这次发版干了啥。
+
+输出后停下。
+
+## 硬约束
+
+- ❌ 不直接执行任何文件修改。只产出讨论结果。
+- ❌ 不碰版本 bump / CHANGELOG / git tag(用户自理)。
+- ❌ **不调 `gh issue create`,不开 issue**。
+- ✅ 全程讨论驱动;Issue 仅在用户确认后产出。
+- ✅ **输出通俗易懂**:用大白话写,别堆术语。

.claude/commands/new-article.md

@@ -0,0 +1,26 @@
+---
+description: 起一篇新文章 —— 按骨架生成 frontmatter + 章节骨架,放进对应卷目录
+argument-hint: "[可选: 主题/线索;留空则交互问]"
+---
+
+# /new-article — 起新文章骨架
+
+按项目骨架([`writing-style.md`](../style/writing-style.md) Part 1)生成一篇新文章的 frontmatter + 章节骨架。
+
+## 输入
+
+`$ARGUMENTS` —— 主题或线索(可选)。留空则依次问:文章类型、目标卷、主题、C++ 标准、难度。
+
+## 流程
+
+1. **确定类型**(四选一):通用文章 / 嵌入式平台教程 / 参考卡 / 标准库组件深入。
+2. **确定位置**:目标卷目录 `documents/vol*/`,文件名 `{序号}-{kebab-case}.md`,`order` = 文件名序号。
+3. **生成 frontmatter**:必填 `title` / `chapter` / `order`;`tags` **必须**来自 `scripts/validate_frontmatter.py` 的 VALID_TAGS(详见 [`documents-frontmatter.md`](../rules/documents-frontmatter.md))—— 1 个 platform + 1 个 difficulty + ≥1 个 topic。
+4. **填章节骨架**:按所选类型的骨架(Part 1.2)放占位结构。
+5. **提醒**:手动更新该卷 `index.md`,否则新文章在站点侧边栏不可达。
+
+## 硬约束
+
+- `tags` 必须来自 VALID_TAGS,否则 pre-commit / CI 校验会挂。
+- `order` 与文件名序号一致。
+- 生成后建议跑 `/preflight` 自检 frontmatter。

.claude/commands/patch.md

@@ -0,0 +1,64 @@
+---
+description: 讨论一轮 patch 小迭代 — 确认后产出【开发工作总结 + 稳定格式的迭代 Issue】到聊天框(只规划,不执行,不开 issue)
+argument-hint: "[可选: 本轮 patch 主题/线索,留空则自动扫描候选]"
+---
+
+# /patch — 小迭代规划(规划者模式)
+
+你现在是**规划者**,不是执行者。本轮你**不修改任何文件、不碰版本号、不建 tag、不调 `gh`**。
+
+## 输入
+
+`$ARGUMENTS` —— 本轮 patch 的主题或线索。为空时,主动扫描发现候选 patch。
+
+## 流程
+
+### 1. 扫描现状
+
+- **累积计数**(累积制核心): 运行
+  `git log $(git describe --tags --abbrev=0)..HEAD --oneline`
+  得到自上次 tag 以来的 patch 提交列表与数量 —— 用户判断"何时升 minor"的依据。
+- 按主题定位相关位置;若涉及内容,读对应 `todo/01x-vol*.md` 确认这个 patch 服务于哪条 next-step(仅作上下文)。
+- ⚠️ 项目 Python 脚本一律用 `.venv/bin/python`(有 PreToolUse hook 强制)。
+- 必要时做 web search 核查事实(准确性优先,token 成本其次)。
+
+### 2. 判定类型并打标(仅用于聊天讨论,不进 Issue)
+
+| 标签 | 含义 | label 建议 |
+|------|------|-----------|
+| 内容 (feat) | 写新内容的一个片段。**完成一部分内容也算 patch** | feature |
+| 修缮 (fix) | 错别字 / 注释错 / 代码缩进或缺行 / 事实性小错 | bug |
+| 批量 (chore) | lint / frontmatter / 404 等机械修复(跨多文件也归此类) | documentation |
+| 示例 (build) | 代码示例编译 / 行为修复 | bug |
+| 工具链 (chore) | 脚本 / CI / 构建配置小修 | enhancement |
+
+### 3. 粒度与边界(累积制 —— patch 是开发的原子单位)
+
+- **patch 是所有开发工作的原子单位**,涵盖全部类型,**包括写新内容的一个片段**。不会因为"动了学习路径"或"写的是新内容"就升级 minor。
+- **不设文件数 / 行数硬上限,也不设类型升级线**。诉求太大就**拆成多个 patch**,不升级 minor。
+- **何时升 minor,纯粹由用户手工判定,与 patch 类型无关。**
+
+### 4. 提案 → 讨论 → 确认(核心是讨论)
+
+- 先用**一句话**讲清这轮打算做什么,作为讨论起点(类型/进度等上下文口头带过即可,**别堆列表**)。
+- 与用户**来回讨论打磨**,直到用户**明确确认**。
+- **保持灵活,不搞死板**:不强制列具体文件、不强制验收标准 —— 讲明白就行。
+- **未确认前,不产出 Issue。**
+
+### 5. 确认后,产出两样东西到聊天框(讨论的最终产物)
+
+**(a) 本轮确认的开发工作** —— 一句话总结聊定的内容。
+
+**(b) 迭代 Issue(Markdown)** —— 套用 `.claude/templates/iteration-issue.md`(极简版:标题 + 一句话 + 一段"本轮打算做什么"),用 ` ```markdown ` 代码块包裹。用户微调后**自行**送 GitHub。
+
+★ **(a)(b) 都必须通俗易懂**:用大白话写,少术语、别堆结构化清单,让没参与讨论的人也能一眼看懂这轮要干啥。
+
+输出后停下。
+
+## 硬约束
+
+- ❌ 不直接执行任何文件修改。只产出讨论结果。
+- ❌ 不碰版本 bump / CHANGELOG / git tag(用户自理)。
+- ❌ **不调 `gh issue create`,不开 issue**。
+- ✅ 全程讨论驱动;Issue 仅在用户确认后产出。
+- ✅ **输出通俗易懂**:用大白话写,别堆术语 —— 用户要能看懂自己收到的 Issue。

.claude/commands/preflight.md

@@ -0,0 +1,37 @@
+---
+description: 提交前自检 —— frontmatter 校验 + markdownlint + 链接/索引检查,汇总 pass/fail
+argument-hint: "[可选: 目标文件或目录;留空则检查已暂存文件]"
+---
+
+# /preflight — 提交前自检
+
+跑一遍 PR 前该过的检查,汇总通过项和待修项。
+
+## 输入
+
+`$ARGUMENTS` —— 目标文件 / 目录(可选)。留空则用 `git diff --cached --name-only` 取已暂存文件。
+
+## 流程
+
+1. **frontmatter 校验**:`.venv/bin/python scripts/validate_frontmatter.py`(**必须用 venv**,系统 python 缺 PyYAML 会全量误报)。
+2. **markdownlint**:`markdownlint <目标 .md 文件>`。
+3. **内部链接**:运行项目的 link check(若有,如 CI 用的脚本),或人工抽检新增 / 改动链接是否可达、`ChapterLink` 的 `href` 不以 `.md` 结尾等。
+4. **索引检查**:若新增或移动了文章,对应卷 `index.md` 是否已更新链接。
+5. **代码示例**(若涉及 `code/`):提醒确认可独立编译(无根 CMakeLists,逐目录构建)。
+
+## 输出
+
+```
+## Preflight 报告
+- [ ] frontmatter: pass / fail（细节）
+- [ ] markdownlint: pass / fail
+- [ ] 内部链接: pass / 待检
+- [ ] 索引更新: 已更新 / 待补
+- [ ] 代码示例: 不涉及 / 待编译确认
+待修清单：...
+```
+
+## 硬约束
+
+- Python 一律 `.venv/bin/python`(有 PreToolUse hook 强制)。
+- 只读检查,不改文件(发现问题列出来,让用户决定怎么改)。

.claude/commands/verify-claim.md

@@ -0,0 +1,39 @@
+---
+description: 验证一条 C++ 断言 —— 编译最小例子 + 查 cppreference,给出成立/不成立的实证(金科玉律固化版)
+argument-hint: "[必填: 要验证的 C++ 断言]"
+---
+
+# /verify-claim — 验证一条 C++ 断言
+
+C++ 语义随标准版本和实现变化,**禁止凭记忆断言**。本命令把这条金科玉律变成可执行流程:对一条断言,**用真实编译输出说话**。
+
+> 命名说明:叫 `/verify-claim` 而非 `/verify`,是为了避开 Claude Code 内置的 `/verify`(验证代码改动是否生效)。本命令专做"C++ 断言的编译实证"。
+
+## 输入
+
+`$ARGUMENTS` —— 要验证的断言(如"`std::move` 作用于 `const` 对象会退化为拷贝")。为空则停下问。
+
+## 流程
+
+1. **写最小复现**:用 Write 把最小 `.cpp` 写到 `/tmp/`(`verify_<主题>.cpp`),只覆盖断言涉及的行为,别塞无关代码。
+2. **编译**(单独一次 Bash):`g++ -std=c++20 -O2 -o /tmp/verify_xxx /tmp/verify_xxx.cpp`;要看生成的指令再加一次 `g++ -std=c++20 -O2 -S -o /tmp/verify_xxx.s /tmp/verify_xxx.cpp`。
+3. **运行**(单独一次 Bash):`/tmp/verify_xxx`。**不要和编译用 `&&` 串。**
+4. **查标准**(必要时):web search cppreference,标标准版本。
+5. **记录编译器**:`g++ --version`。
+
+## 输出
+
+```
+断言：<原文>
+结论：成立 / 不成立 / 部分成立（说清条件）
+标准：C++XX  |  编译器：GCC XX
+最小例子：<code>
+真实输出：<粘贴>
+依据：cppreference 链接 / 汇编片段（如适用）
+```
+
+## 硬约束
+
+- 编译产物**只到 `/tmp/`**;**禁止**在项目目录跑 cmake / make / build。
+- 编译和运行**分两次 Bash**,不串 `&&`。
+- 不确定就如实说"无法确定",**别编输出**。

.claude/hooks/block-bare-python.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# PreToolUse hook (matcher: Bash)
+# 目的:拦截裸 python / python3 调用,强制使用 .venv/bin/python。
+# 原因:系统 python (/usr/sbin/python) 缺少 PyYAML 等依赖,会让
+#       scripts/validate_frontmatter.py 等脚本把全仓文件误报成 error。
+# 策略:任何错误一律 fail-open (exit 0),避免有 bug 的 hook 卡住正常工作。
+
+input=$(cat)
+
+# 从 stdin JSON 中取 .tool_input.command;jq 出错就放行。
+if ! cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null); then
+  exit 0
+fi
+[ -z "$cmd" ] && exit 0
+
+# 显式放行:命令里用了项目 venv 的 python。
+if printf '%s' "$cmd" | grep -q '\.venv/bin/python'; then
+  exit 0
+fi
+
+# 拦截:python/python3 作为"命令"被调用(段首,或紧跟在 shell 操作符 ;|&( 或
+# 包装器 sudo/exec/env/nohup/command/xargs/nice/time 之后)。
+# 不匹配 `grep python`、`echo python` 这类把 python 当参数的情况。
+if printf '%s' "$cmd" | grep -qE '(^|[;|&(])[[:space:]]*((sudo|exec|env|nohup|command|xargs|nice|time)[[:space:]]+)?python[0-9.]*([[:space:]]|$)'; then
+  cat >&2 <<'EOF'
+⛔ [block-bare-python] 检测到裸 python/python3 调用,已拦截。
+本项目必须使用 .venv/bin/python —— 系统 python (/usr/sbin/python) 缺少 PyYAML 等依赖,
+会让 scripts/validate_frontmatter.py 等脚本把全仓文件误报成 error。
+请改写为:.venv/bin/python <你的参数>
+EOF
+  exit 2
+fi
+
+exit 0