ysaa1/harness-workflow/writing-for-agents

Writing for Agents

写并维护 agent 消费的任何面：skills、AGENTS.md / CLAUDE.md / Cursor rules、指针到达的文档、恢复/状态面。包装不同，写作纪律不变——让 agent 每次运行走同样的过程，而不是产出同样的结果。

日常任务流（brainstorm/plan/ship）不经过本 skill：plan 负责建档，本 skill 负责修档案系统。

核心写作纪律（context pointers、两种负载、信息层级、完成判据、leading words、pruning）见 references/writing-core.md；写 skill 的 invocation 选择与 router 规则见 references/skill-mechanics.md。修改本 skill 族任何文档前先读对应 reference。

维护持久指令

1. 发现指定范围内实际生效的文件，区分全局、项目、子目录及生成镜像；Codex 全局入口 $CODEX_HOME/AGENTS.md（默认 ~/.codex），Claude Code 与 Cursor 用各自发现机制。
2. 将规则与当前代码、配置、运行入口和用户授权对照，区分过时事实、冲突、重复、过宽触发和仍有价值的约束；质量维度、更新规则与可选大纲见 references/instructions-maintenance.md。
3. 以具体位置、后果和建议报告问题。只要求审计时只读；已授权时完成范围内删除、合并、迁移和修订，关键合同取舍询问，不重复确认已授权修改。
4. 事实证据说明系统现在如何工作，用户/项目合同说明应该如何工作；不一致时报告，不用现有 bug 覆盖目标合同。

维护恢复/状态面

1. 检查项目已有恢复入口和本次目标；旧任务状态不覆盖当前指令，只读 catch-up 先报告，不默认写文件。
2. 恢复面的格式、写入时机、旧布局迁移与 lessons 写法都以 references/recovery_surface_policy.md（合同 v2）为准，读取顺序见 references/recovery_policy.md。先按它选最小 backend；harness backend 的文件只有 index.md、tracks/<id>.md、lessons.md。开轨道由 plan 做，关轨道由 cleanup 做，旧布局迁移由 sweep 做；本 skill 负责修复格式漂移和改写合同本身。
3. 修复后跑 harness_lint.py（目标项目在 scripts/）确认零 ERROR；没有 lint 时按合同逐条手查。
4. 结构可恢复性检查通过不等于业务验收通过；迁移只在授权且收益明确时做，保留追溯和链接。

Recommended next skill

• 窄修改已验证：结束。
• 多类工作台改造：harness-builder；用户要求独立审阅：review。