agentleFS
openJiuwen-aiopenJiuwen-ai/agent-core/.agents/skills/jw-review/SKILL.md

jw-review

Skill471 starsChanged yesterdayApache-2.0View on GitHub

检视 agent-core/openJiuwen 代码的技术定位、模块约束与 spec 符合性,重点审视基线到候选的行为差异、公共契约、调用链、兼容性和回归证据。适用于工作区、指定提交、分支差异及修复后复查,不限定 PR 场景。

2 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

openJiuwen 代码检视

围绕用户指定的代码范围,以 agent-core 的技术定位、模块规则、当前契约和实际调用链开展检视。 支持本地工作区、明确的单个或多个提交、连续提交范围,以及已确认基线与候选的分支差异;不要求存在 PR。

项目定位与边界

本仓库发布 openjiuwen,提供可嵌入应用的 Agent SDK 与执行框架: core 原语、编码 Harness、多智能体 AgentTeam/SwarmFlow、三方 Harness 协议与 provider、 可选基础设施扩展,以及演进和开发工具。JiuwenSwarm 是下游应用,不在本仓复制产品渠道、UI 或产品会话控制。 检视时区分框架通用契约与宿主策略,不把某一个下游的实现习惯直接提升为框架约束。

模块定位、真实入口与专属关注点按 仓库技术参考 选择读取。 该参考注明来源版本,作为导航;具体 API、字段与状态必须对照待审版本核实。 范围固定、证据核对、问题输出和复查按 检视流程补充 执行。

模块规则与规约依据

  • 从每个变更路径沿祖先目录定位根与模块的 AGENTS.md,继续读取实际受影响的子模块规则, 并按适用的指令优先级处理;若存在 local/override 文件,核实其适用范围,不猜测优先级。
  • 从模块入口及“关联模块/范围/不变量”定位 spec。集中规约主要位于 .agents/agent-docs/specs/harness/、.agents/agent-docs/specs/agent_teams/;三方协议另有 openjiuwen/harness_protocol/SPEC.md。 其他模块按实际文档和导出定位,不假定每个模块都有独立 AGENTS 或 spec,不为检视补造规约。
  • 对每个受影响模块明确:适用指令、spec 的具体文件与条款、代码/测试入口、已知依据缺口。 跨模块变更同时读取生产方和消费方规则;文件移动后核对旧、新目录规则差异。
  • spec 表达当前有效契约;design 表达方案及确认依据;feature/bugfix 解释历史决策与证据。 未确认方案不替代当前契约,历史归档不自动证明当前行为。编号可能重复,引用完整文件名和具体条款。
  • 遇到代码、spec 和 AGENTS 不一致,判断是既存文档漂移、本次遗漏同步还是未经确认的契约破坏。 不以“代码已经这样写了”证明变更合理,也不机械执行已证实过时的接口描述。 检视时报告冲突和修订建议,交给开发同步,不在只读检视中直接修改候选代码或文档。

重点审视差异

检视对象是明确候选相对基线的变化及其影响,不能用候选代码的静态介绍替代差异分析。

  1. 固定候选与基线:记录 SHA、工作区差异及范围内未跟踪文件,区分提交范围与实际运行版本。
  2. 逐个检查新增、修改、删除、重命名和配置/默认值/依赖变化,理解变化前后的可观察行为。 重命名或移动也可能改变导出、包资源、注册发现、相对路径及适用规则。
  3. 对关键差异建立“基线行为 → 候选行为 → spec/设计依据 → 受影响调用链与消费者 → 验证证据”。 特别查找漏掉的调用者、旧数据读者、对称清理路径及未更新的测试/文档。
  4. 变更新建或明显加重的问题才认定为本次引入;既存问题作为上下文,除非本次改动依赖它。 有意破坏兼容需有明确决策、迁移或退役安排与验证;既存过渡实现不授权复制新的耦合。
  5. 范围较大时按风险与执行路径组织覆盖清单;不能只读核心文件或新增测试就宣称完成全量检视。

检视维度

维度重点判断
技术方向与职责通用框架、协议、provider、扩展和宿主策略是否放在正确层?是否出现重复执行环、竞争事实源或反向依赖?
需求、规约与实现验收目标、模块不变量、已确认设计和实际差异是否一致?是否遗漏约束或擅自改变语义?
行为与状态正常、边界、无效输入、重入、并发、取消、关闭和恢复是否维持契约?资源是否成对取得与释放?
公共 API 与兼容导出、签名、默认值、异常/状态码、事件、配置及持久化是否兼容?旧调用者、provider 和数据是否仍能消费?
跨模块与下游参数、结果、事件和生命周期是否贯穿所有受影响消费者?SDK、示例、内置 provider、Team 和下游应用是否遗漏?
权限与数据边界工具实际执行是否受权限和沙箱约束?能力声明、交互审批、路径、敏感数据与跨会话隔离是否可信?
范围、质量与复用是否夹带无关修改?是否复用现有注册、Rail、适配器、持久化和错误模型?抽象是否有真实职责与调用者?
文档与交付API/用户文档、示例、spec、模块规则、feature/bugfix 和包资源是否按影响同步?说明与代码及验证是否一致?
演进、性能与可选依赖是否阻碍已确认迁移方向,或引入无界缓存、阻塞、全局泄漏、循环 import 和强制可选依赖?区分实证风险与推测。

决策记录与行为证据的复查

按 决策归属与替代 核对已有记录的更新及替代范围, 不能因“没有新增文档”忽略有效续写,也不能用新记录掩盖仍然存在的旧契约/数据义务。 按 行为证据 复查实际模型/用户可见结果、真实入口、独立副作用与相关负向对照, 核对证据对应版本、范围及重验条件;需要时按 防错模式提炼 检查约束依据。 只核对本次影响,不在检视中自动修文档、清理历史或要求全仓回放。

按 因果流程与资料可信度 核对历史资料新鲜度、事实与推断、状态权威及跨边界重建链。 结论分别限定盘点、理解、检视和验证范围;未追通的关系与文档漂移明确说明影响,不以资料齐全或符号指纹未变证明行为正确。 本阶段只报告本次相关的资料同步缺口,不自动修改候选文档或启动知识库建设。

证据与结论

沿真实入口追踪注册、装配、执行、事件/结果消费与清理;测试应证明可观察契约, 孤立单测不能证明 Rail 已挂载、provider 能力可端到端使用、冷恢复成功或旧消费者兼容。 按风险运行匹配候选版本的已有行为回归,必要时进行最小复现和同条件基线对照。 区分本次引入、基线已有、环境受限与未执行;CI 证据核对对应 SHA,定向测试通过不覆盖上层失败。

输出 P0–P3、精确位置、触发条件、实际/预期行为、影响、依据及证据,附覆盖范围、未验证项与复查条件。 不要将无来源的风格偏好、理论分层偏好或未验证猜测写成缺陷。 实现问题交给 jw-dev,方案缺口交给 jw-design;修复后固定新候选,复查原问题及相关回归。

保持待审代码和文档不变;不自动提交、切分支、改写历史、启动多代理或操作远端平台。 不运行格式化或静态检查,包括 ruff、pylint、mypy、make check、make format; 模块文件中的同类命令不覆盖本仓禁止执行这些工具的约束。

文档元数据与索引

遵循 作者、设计关联与索引规则:受管文档以 frontmatter 标注 Git author,移除 owner;新 F 平铺在 features/,F/B 显式声明 designs。 写作/修改后自动运行文档同步工具刷新索引;检视只报告缺口,不改写待审资料。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.