simplify-codebase
Prove and remove accidental codebase complexity without breaking behavior.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/tt-a1i--simplify-codebase)HTML
<a href="/listings/tt-a1i--simplify-codebase"><img src="/api/listings/tt-a1i--simplify-codebase/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
让 Codex 安装:
Install the simplify-codebase skill from https://github.com/tt-a1i/simplify-codebase
也可以手动安装到 Codex 的用户级 Skill 目录:
git clone https://github.com/tt-a1i/simplify-codebase.git \ ~/.codex/skills/simplify-codebase
安装后请新建一个任务,让 Skill 目录重新加载。其他支持 `SKILL.md` 的 Agent 环境可将本仓库放入各自的 Skill 目录。
可交互 Cleanup Map 已内置在本 Skill 中,不需要另外安装 Archify。它直接内置精简后的 Architecture 渲染与桌面交互核心,再叠加清理专用编译和 Survey/Change 交互。renderer 需要 Node.js 18 或更高版本,不依赖额外 npm 包;交付的 HTML 不会请求外部字体。
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 95 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: simplify-codebase
- description: Simplification audit or authorized codebase simplification whose stated objective is to remove accidental complexity. Use for evidence-backed deletion or consolidation of dead code, duplicate state, redundant APIs or layers, ownerless abstractions, obsolete compatibility or design records, and over-engineering in any language; also use for 代码简化 or 熵回收. Do not use for general code review, onboarding, style-only refactoring, or performance tuning.
- ---
- # Simplify Codebase
- Reduce the number of concepts and obligations a codebase must keep coherent. Line-count reduction is supporting evidence, not the objective. A successful run may conclude that the inspected surface is already justified.
- ## Select mode and scope
- First choose the authority mode:
- - **Survey** for simplification audit, investigation, or candidate-finding requests. Remain read-only and return ranked evidence.
- - **Change** for explicit simplify, remove, consolidate, refactor, or repository-documentation edit requests. Prove each cut, implement it within the authorized scope, and validate the surviving contract.
- Then choose the coverage scope:
- - **Focused** when the user names a subsystem, symbol, state machine, dependency, or suspected duplication. Cover that boundary thoroughly before expanding outward.
- - **Broad** when the request spans the repository or asks for multiple candidates. Partition the system and account for every in-scope domain.
- Deleting a reachable capability, supported interface, stored representation, or compatibility path is a product decision. Describe the consequence and obtain direction unless the user has already chosen it.
- ## Establish the contract
- 1. Read the repository's instructions, architecture and decision records, manifests, test guidance, and generated-file conventions.
- 2. Inspect version-control state and preserve unrelated work. Identify vendored, generated, migration, fixture, and public-package surfaces before classifying them.
- 3. Trace the runtime path from entrypoints through configuration, registration, dispatch, persistence, processes, and wire boundaries. Record public, dynamic, persisted, generated, and compatibility-sensitive contracts.
- 4. In Change mode, discover the repository's real verification commands and capture a proportional baseline when feasible. A failing baseline narrows what the final checks can prove.
- Preserve authorization, trust-boundary validation, security isolation, accessibility essentials, data-loss prevention, stored-format compatibility, and cleanup that establishes quiescence. Treat changes to these protections as their own explicitly authorized objective, not an incidental simplification.
- The contract map is complete when all in-scope entrypoints and authority boundaries are enumerated, each is traced far enough to name its owner and observable contract, and every uninspected or externally unknowable surface is recorded as a blind spot.
- ## Cover the relevant surface
- For every Broad engagement, and for Focused work involving dynamic architecture or dependency substitution, read [investigation.md](references/investigation.md). Build a coverage map before ranking findings; the first plausible deletion must not end the survey.
- For concurrency, cancellation, readiness, cleanup, defensive copies, validation, authorization, security isolation, accessibility, data-loss prevention, or cross-process data, also read [boundaries-and-lifecycle.md](references/boundaries-and-lifecycle.md).
- Use repository-native search, compiler and linter output, dependency metadata, and history as discovery instruments. Treat their findings as leads until runtime consumers and contracts have been examined.
- ## Build a proof record
- For every in-scope lead that reaches consumer-map evidence or could retire a meaningful contract, record:
- ```text
- Finding ID: a stable report-local identifier such as S1 or S2
- Candidate: the exact contract, representation, or layer to remove or merge
- Locus: the ownership boundary, symbols, and exact paths or lines when verified
- Topology: confirmed node and relationship IDs, primary locus, related nodes, route, and cut set when useful; otherwise not applicable
- Burden: the concepts, synchronization, publication, or testing cost it creates
- Reachability: production, non-production, dynamic, external, and persisted consumers
- Rationale: why it exists and whether that reason remains current
- Cut: declarations, implementations, branches, artifacts, docs, and dependencies affected
- Consequence: observable capability or compatibility behavior surrendered
- Confidence / risk: evidence strength, uncertainty, blast radius, and reversibility
- Proof: the smallest check that would expose an incorrect cut
- Net effect: maintenance concepts removed minus replacement or migration machinery added
- ```
- Keep Finding IDs stable within the run so the summary, proof record, source links, and any visual companion refer to the same candidate. Do not invent a line number, owner, relationship, or route to fill the location fields. Mark unknown facts as unresolved.
- Prove cut boundaries below file granularity when the candidate shares an artifact with surviving consumers. Account for candidate-exclusive selectors, members, fields, keys, registry entries, generated fragments, and fixtures without disturbing the surviving owners.
- Keep or downgrade the candidate when a real consumer exists, dynamic reachability remains unresolved, a current decision still owns the design, the change merely relocates complexity, the result is outside scope or retires no meaningful obligation, or the available check cannot distinguish success from accidental breakage.
- Rank confidence separately from benefit. A high-value guess does not outrank a smaller proved cut.
- Candidate proof is complete when every qualifying lead is classified as ranked, rejected, or unresolved, and every unresolved lead names the fact required to decide it.
- ## Decide and act
- In Survey mode, stop after reporting the ranked evidence. Include important rejected candidates when the rejection teaches something or identifies a concrete missing fact.
- In Change mode, read [execution-and-recovery.md](references/execution-and-recovery.md) and select the strongest authorized cut. One ownership boundary is the default batch size, not a run limit: for an explicitly requested set of cuts, finish and validate each boundary before starting the next.
- If the user requests a simplification proposal, local cleanup annotation, or design-record consolidation, or if a selected change invalidates an ADR, RFC, design note, or architectural inventory, read [decision-records.md](references/decision-records.md). Do not turn an ordinary code audit into a repository-wide documentation purge.
- If the user asks to combine findings from another branch, pull request, task, or agent run, read [integrating-findings.md](references/integrating-findings.md). Preserve evidence, not finding counts.
- Generate a visual companion only when the user explicitly requests one or confirms an offer. If confirmed relationships would make a candidate clearer, explain what the map would clarify and ask before generating it. Without confirmation, complete the text report without a map; do not wait on visual delivery to finish the audit. For authorized visual delivery, read [visual-reporting.md](references/visual-reporting.md) and use the bundled cleanup-map renderer. The map is an optional companion to the proof records, not evidence by itself. Do not write Survey artifacts into the target repository unless the user requested repository files.
- ## Deliver the result
- For a survey, report coverage, ranked proof records, rejected or unresolved high-value leads, and the next fact needed for each uncertainty. When a visual companion was requested or confirmed, report its status and cleanup-map Finding deep links separately.
- Keep the handoff scan-friendly. Lead with the result, then include only the
- proof records, decision-relevant uncertainty, visual links, and validation that
- the user needs. Do not narrate the search process, repeat the same evidence
- under several labels, append generic advice, or keep empty sections. Concision
- does not remove required proof fields: write each field once, in the shortest
- form that preserves its subject, evidence strength, consequence, and boundary.
- For a change, complete the validation and operation receipt defined in [execution-and-recovery.md](references/execution-and-recovery.md). A Before/Cut/After/Verify cleanup map may explain a structural change, but it never replaces the operation receipt. Report each validation layer separately; a narrow green check does not establish broader runtime, deployment, or user acceptance.
README.md · README · 157 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # Simplify Codebase
- **先证明,再删除。让代码库少维护一些事实、状态与契约。**
- [](./SKILL.md)
- [](./LICENSE)
- [](./README.md)
- [](./README.en.md)
- <img src="./assets/hero.png" alt="复杂的软件结构经过证据验证后,收敛为更小、更清晰的系统" width="100%" />
- </div>
- `simplify-codebase` 是一个面向现有代码库的 Agent Skill。它帮助编码智能体识别并安全移除偶然复杂度,同时保护仍然有效的行为、边界与兼容性。
- 它不追求“删得多”。它关心的是:一次改动能否减少团队今后必须持续保持一致的概念和义务。
- ## 为什么需要它
- 代码库里的冗余很少只是“某个函数没人调用”。它也可能是重复状态、失去所有者的抽象、只剩测试消费的接口、早已无效的兼容路径,或者被保留在共享文件中的半截功能。
- 静态检查可以提供线索,但不能单独证明一项删除是安全的。这个 Skill 会继续追踪运行时消费者、动态注册、持久化格式、公共接口、历史决策与验证边界,再决定应该删除、合并、保留,还是标记为暂时无法判断。
- > **核心原则:** 删除代码行只是结果。真正的收益是删除一个需要长期维护的事实、状态、契约或概念。
- ## 工作方式
- | | 聚焦范围 `Focused` | 全库范围 `Broad` |
- | --- | --- | --- |
- | **只读审计 `Survey`** | 深挖一个子系统、状态机或疑似重复点 | 分区覆盖整个仓库,给出候选、反证与盲区 |
- | **授权修改 `Change`** | 证明并完成一个明确的简化边界 | 按所有权边界分批修改,每批独立验证 |
- 每个候选都要形成一份证明记录:
- - 它位于哪个所有权边界、符号、文件,以及能够验证时的行号;
- - 它增加了什么维护负担;
- - 生产、测试、动态和外部消费者分别是谁;
- - 完整删除边界在哪里,包括共享文件内部的成员;
- - 会放弃什么可观察行为或兼容性;
- - 哪个最小验证可以揭示错误删除;
- - 减少的复杂度是否大于新引入的迁移或替代机制。
- ## 它会谨慎对待
- - 公共 API、动态加载和插件注册;
- - 数据格式、迁移、回放与向后兼容;
- - 授权、隔离、输入校验和数据丢失防护;
- - 并发、取消、清理和生命周期所有权;
- - 生成文件、共享资源和仓库外消费者;
- - 仍然有效的 ADR、RFC 与架构约束。
- 发现真实消费者、边界尚未查清,或者简化只是把复杂度搬到别处时,它会建议保留,而不是为了输出结果强行删除。
- ## 安装
- 让 Codex 安装:
- ```text
- Install the simplify-codebase skill from https://github.com/tt-a1i/simplify-codebase
- ```
- 也可以手动安装到 Codex 的用户级 Skill 目录:
- ```bash
- git clone https://github.com/tt-a1i/simplify-codebase.git \
- ~/.codex/skills/simplify-codebase
- ```
- 安装后请新建一个任务,让 Skill 目录重新加载。其他支持 `SKILL.md` 的 Agent 环境可将本仓库放入各自的 Skill 目录。
- 可交互 Cleanup Map 已内置在本 Skill 中,不需要另外安装 Archify。它直接内置精简后的 Architecture 渲染与桌面交互核心,再叠加清理专用编译和 Survey/Change 交互。renderer 需要 Node.js 18 或更高版本,不依赖额外 npm 包;交付的 HTML 不会请求外部字体。
- ## 使用
- ### 审计整个仓库,不改文件
- ```text
- 使用 $simplify-codebase 审计这个仓库,列出最安全、收益最高的简化候选。不要修改文件。
- ```
- ### 调查一个具体问题
- ```text
- 使用 $simplify-codebase 判断这些 readiness 标志是在表达不同的生命周期保证,还是重复状态。
- ```
- ### 实施一个已经证明安全的简化
- ```text
- 使用 $simplify-codebase 删除一个高置信度的偶然复杂度来源。保留仍然有效的契约,完成验证,并给出操作回执和撤销路径。
- ```
- ### 合并其他分支或 Agent 的发现
- ```text
- 使用 $simplify-codebase 复核并整合这个 PR 中的简化建议。保留证据,不保留候选数量。
- ```
- ### 生成可视化伴随报告
- ```text
- 使用 $simplify-codebase 审计这个仓库,并生成带 Finding 深链接的 Cleanup Map。文字证明记录作为权威结果;只画已确认的组件和关系,不要把图上可达关系称为运行时影响范围。
- ```
- ## 输出是什么样的
- 只读审计会交付覆盖范围、排序后的证明记录、重要反例、未决问题和下一条所需证据。
- 修改任务会额外交付实际变更、分层验证结果、剩余风险、操作回执与可执行的撤销路径。一次小范围测试通过,不会被包装成完整的运行时或用户验收。
- 默认交付完整的文字报告。用户明确要求可视化时,Skill 可直接使用内置 renderer 生成经过校验的桌面端交互 HTML;用户未要求时,即使问题横跨多个组件、状态或消费者,也会先说明图能帮助看清什么,得到确认后才生成。未确认不会自动出图,也不影响文字审计完成。
- Survey 按“定位、路径、删除边界、判断”组织,Change 按“变更前、删除边界、变更后、验证”组织。它是 proof record 的视觉伴随物,不替代消费者证明、Change 操作回执或撤销路径。拓扑尚未证明或图没有额外解释价值时,保留带精确文件定位的完整文字报告。
- ## 仓库结构
- ```text
- .
- ├── SKILL.md # 主工作流与判断标准
- ├── PRODUCT.md # 可视化产品定位与渐进披露原则
- ├── agents/openai.yaml # Agent 展示与调用元数据
- ├── references/
- │ ├── investigation.md # 全库调查与候选发现
- │ ├── boundaries-and-lifecycle.md
- │ ├── execution-and-recovery.md
- │ ├── decision-records.md
- │ ├── integrating-findings.md
- │ └── visual-reporting.md # 可选视觉伴随层的真实性与交付契约
- ├── visualization/
- │ ├── cleanup-map.schema.json # 清理专用语义契约
- │ ├── render-cleanup-map.mjs # Cleanup Map → Archify Architecture 编译与交付
- │ ├── archify-core/ # 内置的 Architecture renderer 与桌面 viewer 核心
- │ ├── cleanup-extension.* # Survey / Change 专用交互与视觉扩展
- │ ├── examples/ # Survey 与 Change 输入示例
- │ └── test/ # 契约、路径与产物测试
- ├── docs/validation.md # 行为验证与质量证据
- ├── docs/visual-report-example.md
- └── assets/hero.png # 原创 Hero 视觉
- ```
- ## 质量与边界
- 这个版本经过 Change、Broad、Integration 和 Decision-record 场景验证,也在一个 973 文件的 Python + TypeScript 项目上完成过全库审计。测试方法与已知边界记录在 [docs/validation.md](./docs/validation.md)。
- 视觉伴随层直接内置 Archify 的 Architecture renderer、Signal Flow 视觉系统和桌面 viewer 运行时,并在其上增加 Finding、Survey/Change 阶段、删除边界和按需证据抽屉。默认界面先用一两句话说清问题,再让源码、路径和决策证据随阶段展开;图始终占据主要视觉空间。其他通用图种、仓库 CLI、发布与图库流程没有搬入。来源、修改边界和 MIT 许可保留在 [`visualization/`](./visualization/);报告格式示例见 [docs/visual-report-example.md](./docs/visual-report-example.md)。
- Skill 不能替代产品决策。删除仍然可达的能力、已支持接口、持久化表示或兼容路径时,仍需由使用者明确授权。
- ## 贡献
- 欢迎提交 Issue 和 PR。请优先提供失败案例、遗漏的消费者、错误删除风险或可以复现的验证缺口;这比单纯增加更多规则更有价值。
- ## License
- [MIT](./LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.