需要补充/补强代码注释时：不改逻辑，记录角色边界…

为目标文件或 git diff 文件补充/补强注释与文档注释，使调用方、契约、依赖和非自明约束在代码现场可读。

适用场景

解决思路

1. 确认目标：参数为 `comment-code <対象ファイルまたはディレクトリ> [--lang <言語>]`。指定参数时以该文件/目录为目标；未指定参数时以 `git diff HEAD` 的差异文件为目标。`--lang` 指定时优先按该语言的文档注释格式（JSDoc / docstring / rustdoc 等）处理；未指定时根据扩展名自动判定。
2. 无参数时列出差异文件：运行 `git diff HEAD --name-only`；想把未跟踪新文件也列入时运行 `git ls-files --others --exclude-standard`。若目标为空（无变更且无参数），向用户确认目标。
3. Step 2 调查目标在代码库中的角色：不要只看单个文件，先把握它在整个系统中的位置。
4. 2-1 调查调用方：在代码库中搜索目标文件公开的符号（函数、类、类型、常量），确认哪个层/哪个服务调用它。例如运行 `grep -rn "対象シンボル名" --include="*.ts" --include="*.js" .`。
5. 2-2 确认 import 与依赖关系：查看目标文件依赖的外部模块、服务、配置。例如运行 `grep -n "^import\|^from\|require(" 対象ファイル`。
6. 2-3 确认包/服务边界：用 `package.json`、`go.mod`、`Cargo.toml` 等确认包名与公开 API；若包含服务间通信（HTTP 客户端、事件发布、消息队列），定位连接目标；确认认证/授权中间件、会话管理与目标的关系。
7. 2-4 确认既有注释风格：阅读同一文件/同一包中的既有注释，掌握风格（JSDoc / docstring / rustdoc 等）和语言（日语/英语）。
8. Step 3 添加/补强注释：把 Step 2 掌握的“其他文件、其他服务视角”写入注释。若目标仓库存在 `.claude/rules/code-comment-style.md`，优先遵循；否则按以下要点执行。
9. 写角色/职责边界：写明“该模块承担某服务的某边界”“作为某包的公开接口”。
10. 写调用方上下文：写明从哪个层/哪个服务调用；调用方前提的状态和权限。
11. 写被调用方契约：写明保证返回什么；错误/异常条件和含义（返回 null 还是抛异常等）。
12. 写与其他文件/服务的依赖：写明读者不跨文件就看不出外部依赖、配置、共享状态。
13. 写非自明约束/背景/why：写明为什么这样实现、背景、约束、契约、规格限制。
14. 不写：从签名/类型就能自明的逐字说明（what 的改写）。
15. 不写：容易与实现背离而腐化的重复信息。
16. 不写：只留下已解决经过的注释。
17. 文档注释按语言习惯：TypeScript / JavaScript 用 JSDoc (`/** ... */`)；Python 用 docstring (`"""..."""`)；Rust 用 `///`（条目）/`//!`（模块）；Go 用 `// FuncName ...` 形式；Java / Kotlin 用 Javadoc (`/** ... */`)；其他语言遵循官方文档习惯。
18. 文档注释结构：开头摘要行写“角色/边界”，正文追记调用方/被调用方上下文、非自明约束。
19. 内联注释写 why（为什么这样实现），what 由代码表达。约束、背景、规格上的原因写在对应行或块正前方。积极写入应参照的外部信息（Issue 编号、规格 URL）。
20. 参考好坏例：避免“接收 userId 并返回用户信息”这类 what 逐字改写；改为包含角色、边界和外部视角的注释，如“认证层的公开接口。由 API handler 调用，仅以前提为已通过会话验证的调用（未认证由上流中间件拦截）。委托给 UserRepository，返回从 DB 获取的值。不存在时返回 null（不抛异常）——调用方必须做 null 检查。注：soft delete 的用户也视为 null（规格：issue #142）。”
21. Step 4 自检内容准确性：确认没有自明逐字说明/what 改写；没有与实现背离（不与签名矛盾）；Step 2 调查结果（调用方、依赖关系）是否正确反映到注释。
22. 安全必检：注释中没有 API key、token、密码等秘密信息。
23. 安全必检：注释中没有直接写个人情报（PII）（如用户 ID 示例等）。
24. 安全必检：认证/授权前提条件没有写成容易误解的形式（如误写“无需认证”）。
25. 安全必检：安全上的约束、权限前提被明确且准确描述。若上述检查发现问题，先修正注释内容再继续。
26. 日语风格检查：使用常体（だ・である調）。
27. 日语风格检查：命令、标识符、文件名保持英文，不翻译。
28. 日语风格检查：不要过度使用 emoji。
29. Step 5 用 diff 形式展示变更，并按报告格式汇报：对象文件 `path/to/file.ts`（追加: N 件、补强: M 件）；追加注释观点（调用方、被调用方契约、非自明约束/背景）；安全检查结果（✅ 无问题 / ⚠️ 有警告（详细））；下一步动作（要提交用 create-commit 技能；要更新 CLAUDE.md 用 update-docs 技能）。
30. 不自行提交：提交交给 `create-commit` 技能。
31. 验证：运行 `git diff HEAD`，确认代码逻辑（函数体、控制流）没有被修改；追加注释不与实现矛盾；Step 4 自检清单全部通过。
32. 常见失败规避：若写从签名/类型自明的内容，改为只写 why、调用方前提等非自明信息。
33. 常见失败规避：若没有调查调用方就凭推测写注释，改为在 Step 2 一定用 grep 确认调用方后再写。
34. 常见失败规避：若注释混入秘密/PII，改为在 Step 4 安全检查确认没有秘密/PII。
35. 常见失败规避：若“顺手整理”改了代码逻辑，改为对需要实现变更的地方留 TODO，并引导到 `implement-issue`。
36. 注意：不修改代码逻辑，只追加/补强注释；判断实现有问题时引导到 `implement-issue` 技能。
37. 注意：注释与实现同步；既有注释与实现背离时修正（背离的注释比准确注释更有害）。
38. 注意：详细规约遵循目标仓库；`.claude/rules/code-comment-style.md` 存在时优先，本技能 Step 3 要点是该文件未部署时的 fallback。
39. 注意：把 AI agent 也视为读者；假定“看其他文件就能明白”不成立，Claude 等 agent 会把注释作为主要上下文源。
40. 注意：禁止用 `--no-verify` 等绕过 pre-commit hook；提交时 hook 失败要调查/修正原因后再执行。

适用边界 · 注意事项

• 需要修改代码实现、重构或修复逻辑时：不应使用本技能，改用 `implement-issue`。
• 只需创建提交或同步 CLAUDE.md 时：分别使用 `create-commit`、`update-docs`。
• 目标文件不可读、不在 Git 仓库且未给定明确目标时：无法自动获取 diff，应先提供目标或修复环境。