Files

T

ilaandClaude Fable 5 a89821a571 Initialize harness coding docs from design spec

Split docs/softbox-catalog-design.md into the numbered harness doc set
(00-06, api.md, current-state, agent-context, tasks) following the
harness_coding_docs template and soft_quay conventions. Register the
nine open decision items from the design spec into the 06-tasks
roadmap as W- tasks and backlog entries. Keep the original design
spec as an archived design input with a header note.

Recreated after the repository's previous git history was lost to an
external reset; content matches the original initial commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-20 00:43:58 +08:00

2.5 KiB

Raw Blame History

Agent 上下文清单

agent-context.json 是机器可读的文档路由,agent-context.schema.json 定义结构契约;本文解释 agent 应如何使用它。清单只保存路径和刷新规则,不复制文档正文。

解决什么问题

上下文清单解决的是"本轮该读什么":

先读 bootstrap.always_read,建立最小安全与状态上下文。
根据任务类型选择一个或多个 routes(本仓库:documentation 文档类、protocol 协议/签名类、data 数据模型类、deploy 构建部署类)。
只读取这些路径和本轮任务文件。
用默认分支头提交 SHA 作为 context_ref,用单文件 SHA 作为缓存键。

首次接入与日常会话

首次接入、清单缺失或清单校验失败时,执行 00-ai-start-here.md 中的完整阅读顺序,先修复清单再做功能任务。

日常会话执行:

AGENTS.md
  -> agent-context.json
  -> bootstrap.always_read
  -> 本轮任务文件(docs/tasks/W-<编号>.md)
  -> routes.<任务类型>
  -> 修改与验证

一个任务可以命中多个路由,重复路径只加载一次。

提交 SHA 与缓存

context_ref:领取任务时默认分支的头提交 SHA。
同一会话内文件 SHA 未变化时复用已读内容;默认分支头变化时重新读取清单及变化文件。
本地有未提交改动:本地内容仅对当前 worktree 有效;回复和任务记录中要说明差异。

缓存只用于减少重复读取,不能跨提交假定内容不变,也不能代替 Git 历史。

权威来源

信息	权威来源
仓库级硬规则	最近作用域的 `AGENTS.md`
协议(清单/包/许可证/签名域)	客户端仓库 `soft_quay`(api.md、schemas、corpus);本仓库 `docs/api.md` 仅为摘要
需求、架构、编码纪律	本仓库版本化文档
任务规格与长期执行证据	`docs/tasks/W-<编号>.md`
当前代码行为	代码与真实验证结果

断连 / 客户端仓库不可用降级

同级客户端仓库(../soft_quay)不可读时:

可以基于本仓库已引用的 Schema/corpus 副本(W-001 落实后)继续当前任务。
不得凭记忆修改协议相关实现;涉及协议疑义先恢复对权威源的访问。

清单维护

新增、移动或删除清单引用的文件时,同步修改 agent-context.json,并运行:

python3 scripts/validate_agent_context.py

校验必须确认:必需分区存在、路径为仓库相对路径、引用文件真实存在、最小启动文件齐全。

2.5 KiB Raw Blame History