@chengzhao-dev/dsh-cpp-workflow 0.0.0-stage → 0.1.0

package/skills/developing-cpp/steps/04-implementation.md

@@ -0,0 +1,33 @@
+# 第 4 步：定实现
+
+## 产出
+
+`.cpp` 中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明，不新增公共接口。
+
+## 通用情况
+
+- 函数保持短小；一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不要用注释把长函数切成几段。
+- 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段，不用大段叙述。
+- `.cpp` 第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。若所用 clang-tidy 版本带 `misc-include-cleaner`，这类缺失会被报出来。
+- 实现注释只写「为什么这样做」「这里的边界条件」「这样排序的代价」，不复述代码。
+- 错误处理：可预期失败返回结果类型；合同违反抛异常。捕获异常时按 `const` 引用捕获，只处理能处理的类型，其余继续抛。
+- 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++20 没有 `std::print`。
+- 不写 C 风格强制转换；用 `static_cast` / `std::bit_cast` 等具名转换。
+- 所有权用 `std::unique_ptr`；没有共享所有权的理由时不用 `std::shared_ptr`。
+- 只改注释时，不改可观察行为；只改实现时，不改公共声明。两者同时需要时，先改声明，再改实现。
+
+## 情况
+
+**新实现**：先写最短的直路，让第 1 步的验收通过；重复出现两次以上再抽函数。不要预埋未使用的抽象。
+
+**修缺陷**：先加一个能复现的测试或最小输入，再改实现；修完删掉临时调试输出，保留测试。
+
+**重构**：一次只动一种东西（改名、抽函数、换容器）。每步都让测试保持绿色；行为句不变。
+
+**异常边界**：库内部可以让合同异常向上传播；程序入口捕获 `std::exception`，用 `std::format("错误: {}", error.what())` 打印，返回非零退出码。不要吞掉异常后继续用无效状态。
+
+## 正反例指针
+
+- 实现注释复述代码、分组混乱：`examples/comments.md`「实现注释」。
+- 合同异常与结果类型混用：`examples/exceptions.md`「抛还是返回」。
+- `std::format` 与流输出混用得当：`examples/exceptions.md`「消息格式」。

package/templates/cpp-workflow-project/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: cpp-workflow-project
+description: 当前 C++ 工程的本地事实：工程与组件名、库和程序的边界、入口命令、阶段表、术语增补。开始任何 C++ 任务前先读；这里只写本工程特有的、无法从源码推断的内容。
+metadata:
+  short-description: 当前 C++ 工程事实
+---
+
+# cpp-workflow-project
+
+这是项目模板，不是插件；复制整个目录到目标仓库的 `.agents/skills/` 下，目录名保持 `cpp-workflow-project`，再把下面的空位换成该工程的真实值。目标已有同名文件时只补缺失文件，不覆盖源码、`CMakeLists.txt` 或 `.clang-*`。一个仓库只保留一份 `environment.json`。
+
+## 工程与组件
+
+| 项 | 值 |
+| --- | --- |
+| 工程名 | `<project-name>` |
+| 一句话职责 | `<程序用一句话说明做什么>` |
+| 组件名 | `<component-name>` |
+| 源码根 | `<src-root>` |
+
+同目录的 `environment.json` 三个轴必须填本工程的真实组合；留空时技能仍可能出现，但定构建会停。
+
+## 库与程序的边界
+
+- 库负责：`<领域规则；没有单独库时写“无”>`
+- 程序负责：`<终端输入输出与装配>`
+- 公共头位置：`<component>/include/`
+- 依赖方向：`<程序依赖库；库不依赖终端、GUI 或脚本>`
+
+## 入口命令
+
+```text
+<entry-command>
+```
+
+从仓库根可直接运行；构建、格式化、静态检查、测试和运行都由它串起来。
+
+## 阶段表
+
+- 路径：`stages/stage-table.md`
+- 一个阶段一行，只写可观察行为；没有可观察行为的不进表。
+
+## 术语增补
+
+- `<domain term>`：`<meaning>`
+
+## 可选约定
+
+- 两个具体工程之前不抽共享库。

package/templates/cpp-workflow-project/environment.json

@@ -0,0 +1,5 @@
+{
+  "host": "",
+  "build_host": "",
+  "compiler": ""
+}

package/templates/cpp-workflow-project/stages/stage-table.md

@@ -0,0 +1,4 @@
+# 阶段表
+
+| 阶段 | 可观察行为 | 特殊依据 |
+| --- | --- | --- |