# Longrein 项目协作规则

## 项目目标

Longrein 为强模型提供一组按需组合的工程 Skills 和常驻指令，让 Agent 能自主调查、实现和验证，同时把方向、价值、范围与后果的裁决留给人。

项目追求的不是更完整的流程，而是更可靠的协作循环：现实能够修正模型，证据能够支撑结论，权限能够约束行动，产物能够让下一位继续工作，也让用户继续参与判断。

## 真实对象与工作边界

- 先读当前任务真正涉及的源码、Skill、配置和运行证据，再形成判断。用户描述、文件名、计划和历史结论都是入口，不能代替真实对象。
- 根据当前工作缺少的能力选择 Skill，不为了形式完整增加阶段。调查可以看宽，执行保持在用户授权的范围内；范围、长期责任或不可逆后果变化时，把事实和代价交给用户决定。
- 保护工作树中已有的修改。只改当前请求真正需要的内容，不清理、覆盖或重新组织无关改动，也不自行提交、推送、发布或改写外部状态。
- 结果由可检查证据成立。测试、构建、运行结果、代码路径和真实终态决定完成程度；状态词、作者信心和计划本身不构成证明。

## 权威来源

- `skills/<name>/SKILL.md` 定义 Skill 的触发、责任、核心判断和边界。修改一个 Skill 时检查相邻 Skill，保持职责互补，不用重复规则互相覆盖。
- `global/job.md` 和 `global/soul.md` 是安装到宿主常驻指令块的源文件。修改源文件，不直接编辑生成或安装后的块。
- `cli/src/` 是 CLI 实现源头；`cli/dist/` 是构建产物。安装、更新、卸载、状态和诊断行为都应从源码与实际命令核验。
- `README.md` 面向使用者，只描述稳定、已落地且适合公开理解的产品行为。内部调查材料可以影响判断，但不会自动成为公开文档的内容或引用。
- `references/README.md` 是研究资料的路由入口；这些资料提供判断依据，不自动成为项目规则或 Skill 契约。
- 当前任务的承诺、专业结论和变化历史分别回到各自拥有它们的产物；其他地方只建立必要链接，不维护平行摘要。

## 修改 Skills 与长期规则

- 长期规则只保存跨任务仍会改变行为的稳定经验。一次性要求、临时路径、当前任务事实和偶然成功不自动进入 `AGENTS.md`、global blocks 或 Skills。
- 行为性修改应能对应真实偏差、稳定价值或不可变边界，并由用户批准具体作用域。修改后检查触发、责任、相邻能力、成本和长上下文副作用；没有前后行为证据时，只能称为已修改。
- Skill 主体保留高密度目的、判断和边界。格式、目录、协议或工具细节只有在确实影响行为时才进入核心说明，能由结构或检查保证的内容优先交给结构或工具。
- Skill 只要定义固定持久产物，就在自身 `references/templates/` 中为每种产物提供一个 `*.demo.md` 作为唯一结构来源；`SKILL.md` 和其他 reference 只说明判断与边界并引用 Demo，不内嵌或复制平行模板。开放日志、截图和证据附件不为形式完整制造固定模板。
- 新证据推翻旧前提时，修订所有依赖它的当前产物。旧结论的历史价值不赋予它继续支配当前工作的权力。

## 工程约定与验证

- 项目文档以中文为主；代码标识符、CLI 文案和既有文件语言遵循当前局部风格。面向用户的文字简洁、直接，不暴露内部工作语言。
- 修改 CLI 后至少运行 `npm run typecheck`；涉及构建和发行内容时再运行 `npm run build`。涉及安装状态、managed blocks 或迁移行为时，使用 `longrein doctor` 或等价的本地构建命令核验。
- 修改 Markdown、Skill 或项目规则后运行 `git diff --check`，检查链接、路径、frontmatter、触发边界和重复事实源。行为性变化还需要代表性任务或真实轨迹验证，静态检查只证明结构成立。
- 完成时先给实际结果，再给关键修改、验证和仍未证明的限制。交付信息服从用户当前上下文，不把内部调查过程当成最终答案。