用途
write-docblocks 用于批量处理 PHPDoc 文档缺口。它通过运行 composer docs:coverage:missing 找出缺少文档的文件，并调度并行的 phpdoc-writer 子代理来补齐文档。
核心原则：以每批 5 个子代理的方式处理文件，在保持并行效率的同时避免系统过载。
何时使用
- 文档覆盖率低于目标（类 80%、方法 75%）
- 在创建多个新的服务、控制器或模型之后
- 当 composer docs:coverage:missing 显示大量文件需要文档时
- 用户要求批量编写 PHPDoc
工作流
流程为：运行 composer docs:coverage:missing → 解析输出中的文件路径 → 检查是否还有剩余文件 → 取接下来 5 个文件 → 并行调度 5 个 phpdoc-writer 子代理 → 等待该批完成 → 回到检查步骤；若无剩余文件，则运行 composer docs:coverage 验证改进情况。
执行步骤
1. 获取缺失文件
composer docs:coverage:missing 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep '\.php$'
该命令会去除 ANSI 转义码并仅提取文件路径，例如：
Console/Commands/ProcessDataCommand.php
Http/Controllers/AuthController.php
Services/AuthService.php
2. 每批处理 5 个文件
对每批 5 个文件，在单条消息中使用多个 Task 工具调用并行调度 phpdoc-writer 子代理：
Task(subagent_type="phpdoc-writer", prompt="Write PHPDoc blocks for app/Console/Commands/ProcessDataCommand.php - read the file, understand its purpose, and add comprehensive docblocks for the class and all undocumented methods.")
Task(subagent_type="phpdoc-writer", prompt="Write PHPDoc blocks for app/Http/Controllers/OAuthController.php - read the file, understand its purpose, and add comprehensive docblocks for the class and all undocumented methods.")
// ... 3 more in same message
关键：全部 5 个 Task 调用必须放在同一条助手消息中，才能并行运行。
3. 等待该批完成
在开始下一批之前，等待全部 5 个子代理完成。这样既能保持并行，又能防止资源耗尽。
4. 重复直到完成
持续按批处理，直到所有文件都有文档。
5. 验证覆盖率
composer docs:coverage
确认覆盖率向目标（类 80%、方法 75%）提升。
子代理提示词模板
Write PHPDoc blocks for app/{PATH}
1. Read the file thoroughly to understand its purpose
2. Check what's already documented vs missing
3. Add comprehensive docblocks for:
- Class-level documentation explaining purpose and context
- All undocumented public methods with @param, @return, @throws
- Protected/private methods with brief explanations
4. Follow project-specific conventions and domain terminology
5. Run pint after editing: ./vendor/bin/pint {file}
Target audience: New developer on their first day.
常见错误
- 顺序调度：一次只处理一个文件会浪费时间。应使用每批 5 个并行处理。
- 未使用单条消息：把多个 Task 调用分散在不同消息中会顺序执行。应把 5 个都放在同一条消息里。
- 跳过验证：最后务必运行 composer docs:coverage 确认改进。
- 忘记 pint：子代理应在编辑后运行 ./vendor/bin/pint 以保持代码风格。
适用场景与限制
该技能面向 PHP 项目，依赖 composer 脚本 docs:coverage:missing 与 docs:coverage，以及 phpdoc-writer 子代理和 pint 工具。资料未提供其支持的具体框架版本、安装方式、收费信息或平台限制。