Codebase Convergence

一个帮助你梳理代码、架构、界面与 Markdown 文档一致性的 Codex Agent Skill。

codebase-convergence 用于让已有仓库更容易理解、更容易维护。它以证据为基础定位矛盾、重复与局部缺陷，只做安全且范围明确的修整；凡是涉及数值、业务规则、交互行为、公开接口或受保护文案的改动，都会先汇总为一份待确认清单，而不是擅自重构。

它能做什么

适合在以下场景使用：

• 排查互相矛盾的文档、过期链接或重复说明。
• 收敛同一个事实的多个来源，明确唯一权威入口。
• 梳理模块、状态、UI 与领域文档之间的职责归属。
• 修复局部且不改变产品行为的代码或界面问题。
• 在实施前评估一个新的模块边界是否真的有价值。

它并不是“把仓库全部推倒重写”的工具。数值、阈值、业务规则、公开接口、交互行为，以及用户指定的文案，都需要由你明确确认后才会修改。

安装

将仓库克隆到本机 Codex Skills 目录：

mkdir -p ~/.codex/skills
git clone https://github.com/01-Yang/codebase-convergence.git \
  ~/.codex/skills/codebase-convergence

安装后重新打开一个 Codex 任务，使 Skill 被重新发现。更新已有安装时：

git -C ~/.codex/skills/codebase-convergence pull --ff-only

请保留 SKILL.md 与 agents/openai.yaml：前者是完整工作说明，后者提供 Codex 中的展示名称、简介和默认提示词。

如何使用

在 Codex 中直接调用：

使用 $codebase-convergence 审查这个仓库，只收敛可以安全处理的问题，
并把所有涉及数值或行为的决定整理出来让我确认。

还可以这样提问：

使用 $codebase-convergence 找出与架构权威文档重复或冲突的说明，并只修复无需产品决策的问题。

使用 $codebase-convergence 从用户操作、状态归属到最终渲染追踪这个 UI 问题，
然后只做不改变现有行为的修复。

使用 $codebase-convergence 评估这个模块边界是否值得建立；在我选择之前不要实现它。

工作方式

明确范围与受保护内容
        ↓
基于证据建立现状基线
        ↓
可直接收敛的问题  ──→  小范围、可追溯地修复
        ↓
需要决定的问题    ──→  汇总为一次确认清单
        ↓
架构候选项        ──→  独立评估，不直接实施
        ↓
检查差异、链接与相关验证

核心原则

• 先阅读仓库说明、领域词汇表和相关 ADR，再判断架构问题。
• 使用仓库已有的领域术语，不擅自发明另一套命名。
• 保留无关的工作区改动，以及用户明确保护的内容。
• 未获明确批准，不修改或“顺手统一”任何数值、阈值、比例或限制。
• 不静默改变状态流转、交互行为、视觉约定或公开接口。
• 每个事实只保留一个来源；其他位置链接到权威来源，不再复制一份摘要。
• 优先做局部、可验证的修复，不用猜测性的抽象扩大改动范围。

工作流程

1. 建立基线：梳理相关代码路径、状态或数据归属、UI 流程、测试与 Markdown 文档，并将发现区分为“可直接收敛”“需要决定”“架构候选”。
2. 一次性确认决定：把所有尚未确定的数值、规则、行为、锁定内容和所有权冲突汇总成一份决策清单。
3. 处理直接收敛项：只修复已确认的重复、过期引用、非锁定文案冲突，或不改变行为的局部缺陷。
4. 独立评估架构候选：说明模块、接口、边界、深度与局部性；会改变接口、行为或所有权的方案必须先经确认。
5. 验证并交接：检查最终差异、Markdown 标题和链接，运行现有的相关验证，并区分既有失败与本次引入的问题。

完整的操作规则见 SKILL.md。

文件说明

路径	用途
SKILL.md	Skill 的完整约束、工作流程、架构评估方式与交接要求。
agents/openai.yaml	Codex 中显示的名称、简短说明与默认提示词。

参与维护

保持这个 Skill 简洁、具体，并能适配已有仓库。任何流程改动都应守住它的核心承诺：让安全的收敛工作易于执行，让重要选择清楚地交还给用户。