用途:scratchpad-working-files 是一套用于管理“不属于仓库历史的工作文件”的约定,覆盖笔记、进度跟踪、报告、手动测试辅助脚本、临时数据库等内容。其目标是把临时产物集中在一处,避免散落在系统临时目录或项目之外而在会话之间丢失。若 AGENTS.md 对该主题另有约定,则以 AGENTS.md 为准。
主要能力与处理规则:
- 位置:所有临时内容都放在仓库根目录的 .scratchpad/ 中,禁止使用 /tmp、系统临时文件夹或会话专用的临时目录。
- Git 忽略:首次写入前确认 .scratchpad/ 已在 .gitignore 中;若没有,则在其单独的提交中加入:
Working notes
.scratchpad/ 3. 目录布局:以功能 slug(来自分支)作为子文件夹,例如 .scratchpad/<slug>/,其中可包含:progress.md(步骤、状态与提交,用于中断后恢复)、interview-decisions.md、verification-report.md、browser-test-report.md、redteam-report.md、change-list.md、production-readiness-report.md、retrospective.md、pr-body.md、manual-env.sh(启动隔离服务器的辅助脚本)、manual-data/(手动检查使用的隔离数据,如临时数据库、fixtures)、scripts/(复现与验证脚本)、transcripts/(归档的会话记录)。 4. 报告:每个长任务结束时都要生成报告文件,即使用户没有要求;并告知用户文件路径。仅存在于聊天中的报告在上下文压缩后会丢失。 5. 进度文件:在任何循环过程中保持 progress.md 为最新,使用步骤、状态、提交、备注等列记录,例如:
| Step | Status | Commits | Notes |
|---|---|---|---|
| 1 Walking skeleton | done | 0c31ee8, 84ae35f | |
| 2 Cancel an order | in progress | ||
| 若会话因用量限制、崩溃或跨天而中断,下一次会话读取该文件继续。 |
手动测试环境:手动检查的数据(临时数据库、fixtures)放在 .scratchpad/<slug>/ 内,绝不使用真实数据;使用其他会话不占用的专用端口;把启动和停止辅助脚本放入 manual-env.sh,使每次检查只需一条命令;按启动辅助脚本保存的 PID 停止自己启动的每个服务器,不要使用会匹配到自身命令的 pkill -f 模式(可能停掉自己的 shell);停止后等待端口释放(lsof -iTCP:<port> -sTCP:LISTEN),因为 kill 后立即 pgrep 仍可能看到进程;变更检查与备份也放在 .scratchpad/<slug>/ 而非 /tmp;测试凭据放在辅助脚本中,不放在聊天消息里。
委派子代理时的简报要求:写入任何文件都只能在 .scratchpad/<slug>/ 下;除非任务明确说明,否则不编辑仓库文件;若启动服务器,使用自己的端口和数据,并在结束时停止;说明哪些结论经过验证、哪些是推断。
适用场景:需要在开发或审查过程中保留临时笔记、进度、各类报告、手动测试脚本与隔离数据,并希望这些内容不进入仓库历史且能在会话中断后恢复。
限制:这是一套约定性文档,不提供具体工具实现;是否遵循取决于使用环境;具体文件内容与格式除文中示例外暂未提供更多细节。