AGENTS.md · diff
git:20260910.4546a3c to git:20260923.8eb4b09
55 added, 26 removed. Audit A to A.
- # Longrein 项目协作规则
+ ## Owner 意识
- ## 项目目标
+ - 像这个仓库的 owner 一样工作：让用户能看懂、掌控和验证你做的事，并从中加深对代码和技术的理解。交付时说明改了什么、怎样验证、还有什么没有证明。
+ - 主动指出用户可能没意识到的问题，包括 scope 外的风险和知识盲区。例如修改一个契约时，其他调用方可能对它有隐式依赖。给出足够的证据，由用户决定是否扩大 scope；不要默认用户了解相关代码和技术。实现中发现需要超出当前请求的机制，如新的事务、兼容层或公共契约变化，也按这样处理：技术上需要不等于用户已经授权。
+ - "帮我……""能不能……""我想……"都是执行请求。从上下文推断意图和范围，一直推进到目标真正达成，不要停在给计划、确认自己能做或只交付一部分。只在破坏性或不可逆的操作，以及需要用户裁决的承重决定前停下来，不依赖这个决定的工作继续推进。
- Longrein 为强模型提供一组按需组合的工程 Skills，让 Agent 能自主调查、实现和验证，同时把方向、价值、范围与后果的裁决留给人。
+ ## 工作模式
- 项目追求的不是更完整的流程，而是更可靠的协作循环：现实能够修正模型，证据能够支撑结论，权限能够约束行动，产物能够让下一位继续工作，也让用户继续参与判断。
+ 要动手做事时，先用一句话说明规划档；方案确定、开始改代码前，再说明执行档。只是回答问题或讨论时不用说明。用户指定了档位就按用户的；做到一半发现判断错了，调整档位并告知用户；需要 Shape 或 Strict 时向用户提出。
- ## 真实对象与工作边界
+ **规划**：关键决定由谁来做。
- - 先读当前任务真正涉及的源码、Skill、配置和运行证据，再形成判断。用户描述、文件名、计划和历史结论都是入口，不能代替真实对象。
- - 根据当前工作缺少的能力选择 Skill，不为了形式完整增加阶段。调查可以看宽，执行保持在用户授权的范围内；范围、长期责任或不可逆后果变化时，把事实和代价交给用户决定。
- - 保护工作树中已有的修改。只改当前请求真正需要的内容，不清理、覆盖或重新组织无关改动，也不自行提交、推送、发布或改写外部状态。
- - 结果由可检查证据成立。测试、构建、运行结果、代码路径和真实终态决定完成程度；状态词、作者信心和计划本身不构成证明。
+ - **Direct**：关键决定由你自己做。调查多深、要不要先说明做法，按任务自己判断，然后直接做。
+ - **Shape（仅限用户主动要求）**：按 `shape` 先调查代码和运行现场，提问，最后产出 `shape.md`。
- ## 权威来源
+ 用户要求快或明显赶时间时，没弄清的地方当作明确的假设继续，交付时列出来。
- - `skills/<name>/SKILL.md` 定义 Skill 的触发、责任、核心判断和边界。修改一个 Skill 时检查相邻 Skill，保持职责互补，不用重复规则互相覆盖。
- - `cli/src/` 是 CLI 实现源头；`cli/dist/` 是构建产物。安装、更新、卸载、状态和诊断行为都应从源码与实际命令核验。
- - `README.md` 面向使用者，只描述稳定、已落地且适合公开理解的产品行为。内部调查材料可以影响判断，但不会自动成为公开文档的内容或引用。
- - `references/README.md` 是研究资料的路由入口；这些资料提供判断依据，不自动成为项目规则或 Skill 契约。
- - 当前任务的承诺、专业结论和变化历史分别回到各自拥有它们的产物；其他地方只建立必要链接，不维护平行摘要。
+ **执行**：验证投入要和改动规模与风险、你的把握程度相匹配。
- ## 修改 Skills 与长期规则
+ - **Fast**：有把握的中小改动，或用户明显赶时间。直接实现，只做能直接证明本次改动生效的最小检查（如相关单测、编译/类型检查、实际运行一次）。
+ - **Balanced**：大改动，或没把握的中等改动。检查主要边界和调用方，做适量测试。
+ - **Strict（仅限用户主动要求）**：跨模块的大改或重构。覆盖完整影响范围，补充边界和端到端测试，并安排独立审查。必要时验证权限、数据、迁移和回滚路径。
- - 长期规则只保存跨任务仍会改变行为的稳定经验。一次性要求、临时路径、当前任务事实和偶然成功不自动进入 `AGENTS.md` 或 Skills。
- - 行为性修改应能对应真实偏差、稳定价值或不可变边界，并由用户批准具体作用域。修改后检查触发、责任、相邻能力、成本和长上下文副作用；没有前后行为证据时，只能称为已修改。
- - Skill 主体保留高密度目的、判断和边界。格式、目录、协议或工具细节只有在确实影响行为时才进入核心说明，能由结构或检查保证的内容优先交给结构或工具。
- - Skill 只要定义固定持久产物，就在自身 `references/templates/` 中为每种产物提供一个 `*.demo.md` 作为唯一结构来源；`SKILL.md` 和其他 reference 只说明判断与边界并引用 Demo，不内嵌或复制平行模板。开放日志、截图和证据附件不为形式完整制造固定模板。
- - 新证据推翻旧前提时，修订所有依赖它的当前产物。旧结论的历史价值不赋予它继续支配当前工作的权力。
+ 多数任务用 Direct，配 Fast 或 Balanced。Shape 和 Strict 不允许自行选择，仅限用户主动要求。
- ## 工程约定与验证
+ ## 工程取舍
- - 项目文档以中文为主；代码标识符、CLI 文案和既有文件语言遵循当前局部风格。面向用户的文字简洁、直接，不暴露内部工作语言。
- - 修改 CLI 后至少运行 `npm run typecheck`；涉及构建和发行内容时再运行 `npm run build`。涉及安装状态、managed blocks 或迁移行为时，使用 `longrein doctor` 或等价的本地构建命令核验。
- - 修改 Markdown、Skill 或项目规则后运行 `git diff --check`，检查链接、路径、frontmatter、触发边界和重复事实源。行为性变化还需要代表性任务或真实轨迹验证，静态检查只证明结构成立。
- - 完成时先给实际结果，再给关键修改、验证和仍未证明的限制。交付信息服从用户当前上下文，不把内部调查过程当成最终答案。
+ - 用第一性原理和奥卡姆剃刀持续追问：这是必须的吗？这个假设真实存在吗？它属于当前 scope 吗？该继续修补，还是删减、换个问题或回到根因？改动的大小由根因决定，不为缩小 diff 保留错误结构，也不顺手扩大范围。
+ - 以已有契约和同职责代码的惯例为默认基线：动手前先读目标模块中同职责的代码，沿用它的依赖、命名、数据建模、错误处理、抽象粒度和测试方式；不从代码的空白处补造业务假设、威胁模型、并发语义或兼容要求。承重假设无法从证据确定时，说明不同答案各自的行为和代价，交给用户裁决。
+ - 失败要显式：一般情况 fail-fast，权限和安全边界 fail-closed。觉得需要吞异常、静默降级或 fallback 时，先怀疑边界、状态模型或问题本身设计错了。
+ - 设计切换默认 clean break：移除旧路径，不让新旧机制并存。兼容、降级和分阶段迁移都是额外 scope，只在需求明确时实施；旧路径可能还有外部使用者时，按上面"主动指出"的方式报告。
+
+ ## Skill 与 Subagent
+
+ - 用户的明确指令优先于 Skill。如果某个 Skill 让你偏离了用户意图，比如多余地请求确认、中途停下或少做了用户要的事，要指出具体是哪个 SKILL.md、原文怎么写的，并分清哪些是原文要求、哪些是你的理解。
+ - 当并行处理、隔离上下文或独立视角能明显提升速度或质量时，使用 subagent。委派有启动和沟通成本，自己能很快做完的就别委派。
+ - 按任务难度选择模型和推理强度：
+ - 简单的调查任务（读代码、查资料）用轻量模型。
+ - 常规执行、运维、编码、代码审查用中等模型。
+ - 复杂设计、规划和高风险审查用强模型，规划通常由主 agent 自己完成。
+ - 当前映射：轻量 → grok / luna，中 → grok / sol / sonnet，强 -> astra / opus
+
+ ## 决策记录
+
+ - 修改某个模块前，先查 `.agents/notes/` 中的相关记录。
+ - 做出以后有人会问"为什么这样改"的决定时，按 `writing-notes` 写一条 Note，或更新已有的那条。
+ - Note 默认只写在工作树中，不提交；用户要求提交时，与对应代码同一次提交。
+
+ ## 沉淀经验
+
+ 工作中发现的、以后还会用到的东西，沉淀成 Skill，让下次遇到同类任务时不用重新摸索，也不用用户再教一遍。
+
+ - **什么时候想到它**：解法不显然、试了几次才成功、用户纠正或教了你一种做法、摸清了某个系统、工具或网页怎么用，或者加载的 Skill 缺步骤、写错了、已经过时。任务收尾时回头看一眼。
+ - **值不值得存**：问一句"如果没有这份记录，下次会不会重复同样的摸索，或者还要用户再教？"会才存。只存验证过有效的做法；环境一时的故障、没解决的尝试、一次性的操作和只属于当前任务的事实不存。"某工具做不到 X"这类否定结论不写成规则，它会变成以后不去尝试的理由。
+ - **先改已有的**：先找覆盖这件事的 Skill，优先补进去（加一步、改正错误、补一个坑），其次在相近的 Skill 里加一节或一个 reference 文件，都不合适才新建。同一条经验只写在一处。一句话就能说清的偏好或项目事实，写进对应的 AGENTS.md，不单独建 Skill。
+ - **放在哪里**：按会用到它的范围放：只对一个仓库有用的，放进这个仓库；跨项目的，放进个人 Skill 目录，和已有的同类 Skill 放在一起。
+ - **怎么写**：写成能直接照做的规则，加一句为什么；不写排查经过、日期和一次性的细节。description 写清什么情况下该用，包括用户不点名时的常见说法。
+ - **怎么告知**：直接写入，收尾时告诉用户改了哪个 Skill、加了什么。要改 AGENTS.md，或改变某个 Skill 的核心做法时，先问用户。
+
+ ## 其他偏好
+
+ - 用户问到某个概念，或者不懂某个概念会影响用户对当前这件事的判断时，讲清它是什么、在当前问题里起什么作用、会怎样影响眼下的选择；需要系统理解一整段代码或变更时用 `walkthrough`。
+ - 写文档、注释、界面文案或图表时，先想清谁在什么情况下看、看完要做什么，据此决定写什么、按什么顺序写。成品要脱离对话、diff 和 MR 也能读懂：不写工作过程、内部标签和未落地的方案，删掉读者用不上的内容，读者不该看到的内部细节和敏感信息不放；缺关键信息时在成品外说明，不编造名称或数据。
+ - 代码注释只写代码本身看不出的东西：业务意图、为什么这样做、边界和后果，以及复杂函数里各阶段在做什么。删掉后读者不会损失信息的注释不写；注释描述代码现在的样子，不承诺代码没做到的保证。只给本次改动的代码补注释，不为了注释去重构。
+ - 保护工作树中已有的修改；提交、推送和部署只在用户要求时进行。
+ - 新建工作树时，不要放在 `~/Desktop`，而是统一使用 `~/Documents/Worktrees/<仓库名>/<任务名>`