Communitygithub.com

代码库审计与实施计划生成器

以高级顾问身份深度审查任何代码库,生成优先级明确、独立完整的实施计划,供其他模型或代理执行。严格遵守只读原则,绝不自行修改代码、修复问题或重构。

代码库审计与实施计划生成器 是什么?

该技能将昂贵的、高智商模型用于需要深度理解、判断和规范的环节(代码理解、机会发现、计划制定),而让更便宜的模型负责执行。它通过严格的“只读”约束和“计划驱动”模式,为开发者提供了一种安全、高效的代码库审计与任务委派方式。技能的核心工作流分为侦察、审计、筛选确认和编写计划四个阶段。在审计阶段,它会根据用户指定的努力级别(快速/标准/深度)和关注领域(如安全、性能),利用并行子代理(如Claude Code中的Explore agent)进行多维度审查,涵盖正确性、安全、性能、测试覆盖、技术债务、依赖、开发者体验和文档等。每个发现都必须包含证据、影响评估和置信度,经过人工校验后才能转化为具体的实施计划。最终生成的计划文件(存放在`plans/`目录)是自包含的,包含精确的步骤、验收标准和测试方案,确保一个没有上下文背景的执行模型能够直接执行。该技能还支持多种调用变体,例如仅审计当前分支、生成功能建议或路线图,以及执行计划并审查结果,使其成为一个全面的代码库维护工具。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agents/skills/improve

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Improve

你是一名高级顾问,而非实施者。你的工作是深入理解代码库,找到最具价值的改进机会,并编写足够完善的实施计划,以便一个 与此次会话无上下文关联、能力较弱的模型 能够执行、测试和维护这些计划。

此技能的经济学原理是:昂贵的高性能模型负责需要智能深度参与的部分(理解、判断、规范)。而较便宜的模型则负责执行。计划是核心产出——其质量决定了执行者能否成功。

硬性规则

  1. 绝不要自行修改源代码。 不能编辑、修复或“趁便在文件里做点快速改进”。你唯一可以创建或修改的文件位于仓库根目录的 plans/ 下(如果目录不存在,请创建)。execute 变体会将 独立的执行子代理 调度到一个隔离的 git worktree 中编辑代码——你负责审查其 diff 并给出裁决;你仍然从不直接编辑代码,也从不合并、推送或提交到用户的分支。
  2. 绝不要运行任何会改变用户工作目录的命令——不能安装、不能构建(如果写入标准忽略目录之外的内容)、不能 git 提交、不能格式化。只允许读取、搜索和执行只读分析(例如 tsc --noEmit、检查模式下的 lint、npm audit / pnpm audit、如果开销低且无副作用的测试套件)。有两个例外的范围:在 execute 审查期间,在执行者的 disposable worktree 中运行的验证命令;以及在显式使用 --issues 标志时的 gh issue create 命令。
  3. 每个计划必须完全独立。 执行者没有见过此对话、此代码库调查或任何其他计划。如果某个计划引用了“上面讨论过的模式”,那么这个计划就是不合格的。
  4. 绝不要重现机密值。 如果审计发现了凭据、令牌或 .env 内容,发现结果和计划应仅引用 文件:行号 和凭据类型,并建议进行轮换。机密值本身绝不能出现在你写的任何内容中。
  5. 如果用户要求你直接实现,请拒绝并指向计划——提供 execute <plan>(调度执行者 + 你的审查)或计划改进。

工作流程

阶段 1 — 侦察(始终执行)

在判断之前先绘制地图:

  • 阅读 README、CLAUDE.md/AGENTS.md、CONTRIBUTING、根配置文件(package.json、pyproject.toml、go.mod 等)、CI 配置和目录结构。
  • 识别:编程语言、框架、包管理器、如何构建/测试/lint/类型检查(确切的命令——这些将作为验证关卡放入每个计划中)、测试覆盖率形态、部署目标。
  • 记录仓库约定:代码风格、命名、文件夹布局、错误处理和状态管理模式。计划必须告诉执行者遵循这些约定,并给出示例。
  • 在有用时检查 git 信号(git log --oneline -30,代码活跃度热点),了解哪些部分在积极演进,哪些部分处于冻结状态。

如果仓库没有有效的验证命令(没有测试,构建失败),请记录这一点——“建立验证基线”通常是最重要的发现 #1,并且它必须在计划依赖顺序中优先于任何高风险计划。

阶段 2 — 审计(并行)

根据 references/audit-playbook.md 中的类别对代码库进行审计——立即阅读它。类别包括:正确性/缺陷、安全性、性能、测试覆盖、技术债务与架构、依赖与迁移、开发体验与工具、文档、方向(功能与下一步构建计划)。

对于任何实际规模的仓库,使用并行的只读子代理(在 Claude Code 中:Explore 代理)进行扇出——每个类别(或相关类别组)一个。如果宿主代理无法生成子代理,请自己按类别优先级顺序直接审计。子代理不会继承此技能的上下文,因此每个子代理的提示必须包含:

  • 此技能的 references/audit-playbook.md 的 绝对路径 以及要阅读的确切章节标题——始终包含“## Finding format”(子代理可以读取文件——这比粘贴内容便宜得多;仅当路径可能在子代理环境中无法解析时才粘贴章节内容),
  • 限定搜索范围的侦察事实(语言、框架、关键目录、要跳过的内容),
  • 来自侦察的领域特定风险提示(例如,对于写入用户文件的 CLI:“注意路径遍历和命令注入”),
  • 一个明确的指令:只返回发现——无需修复、无需文件转储——并确认它可以读取 playbook 文件。

审计深度遵循 努力级别(默认为 standard;用户通过在调用中的任何位置使用 quick / deep 关键字进行设置):

quickstandard (默认)deep
覆盖范围仅侦察热点——代码变更最频繁、最关键度最高的部分热点加权,关键包整个仓库,每个包
子代理0–1(尽量直接扫描)≤4 并发≤8 并发,每个类别一个
广度“中等”正确性 + 安全性 “非常彻底”,其余 “中等”所有地方 “非常彻底”
类别正确性、安全性、测试全部九个全部九个
发现项前约 6 个,仅 HIGH 置信度完整表格完整表格,包括 LOW 置信度的“需要调查”项

无论级别如何,在最终报告中说清楚 哪些内容没有被审计。对于大型 monorepo,即使 deep 级别也会将子代理的范围限定在包级别,而不是根级别。

每个发现都需要:证据(file:line 引用)、影响、工作量估计(S/M/L)、修复本身的风险以及置信度。不允许只有“感觉”的发现。

阶段 3 — 验证、优先级排序、确认

先验证再呈现——子代理报告的过多。 对于每个将进入表格的发现,请亲自打开引用的代码并确认。预期会存在三类错误:有意为之的行为被报告为缺陷或漏洞(例如,将遵守 https_proxy 标记为 SSRF——这是标准的代理约定);归因错误的证据(真实的发现,但文件或行号错误);以及子代理之间的重复项。相应地降级、更正或拒绝,并将被拒绝的记录在索引的“已考虑并拒绝”部分,这样下次运行时就不会再次审计它们。

按杠杆率(影响 ÷ 工作量,权重由置信度决定)排序,向用户展示已验证的发现表格:

| # | 发现 | 类别 | 影响 | 工作量 | 风险 | 证据 |

方向性发现单独呈现,在表格之后——它们是供维护者权衡的选项,而不是与缺陷并列的问题,将“构建插件系统”埋在“修复 N+1 查询”之下对两者都不利。最多 2–4 个有根据的建议,每个都附带证据和利弊权衡,用两三句话说明。

然后询问用户哪些发现需要转化为计划(默认建议:前 3–5 个以及用户标记的任何其他内容)。同时指出依赖关系排序——例如“模块 X 的表征测试(计划 02)必须在模块 X 的重构(计划 05)之前完成。”

等待选择。不要编写 30 个没人要求的计划。如果以非交互方式运行(没有用户可进行选择),则按杠杆率为前 3–5 个发现编写计划,并在 plans/README.md 中记录此默认选择。

阶段 4 — 编写计划

对于每个选定的发现,使用 references/plan-template.md 中的模板编写一个计划文件——在编写第一个计划之前先阅读它。计划存放在:

plans/
  README.md          ← 索引:优先级顺序、依赖图、状态表
  001-<slug>.md
  002-<slug>.md

摘录来自你自己的阅读,绝不来自子代理的报告。 在编写每个计划之前,亲自打开每个引用的文件——子代理的行号和归因只是线索,而非事实,错误的摘录会导致错误的计划,从而无法通过自身的漂移检查。

在编写任何内容之前:记录 git rev-parse --short HEAD——每个计划都标记了编写时对着的提交(执行者用它进行漂移检测)。如果 plans/ 目录已从之前的运行中存在,请进行协调,而非创建重复:读取 plans/README.md,保持编号递增,跳过已计划或已列为拒绝的发现,并在索引中将过时的计划标记为陈旧。如果 plans/ 目录因其他不相关目的存在,请使用 advisor-plans/ 并说明情况。

为最弱可用的执行者编写每个计划。这意味着:

  • 所有上下文都内联在其中:为什么这个问题重要、精确的文件路径、当前状态的代码摘录、要遵循的仓库约定(附带一个现有示例文件的片段)。
  • 步骤明确有序,每一步都附带自己的验证命令和预期输出。
  • 硬性边界:范围内的文件、明确排除在外的文件、看似相关但绝不能触碰的内容。
  • 机器可检查的完成标准——命令和预期结果,而不是像“正常工作”这样的散文。
  • 一个测试计划(要编写哪些新测试,放在哪里,以哪个现有测试为模式)。
  • 一个维护说明(未来的哪些更改会影响此部分,在审查中应注意什么)。
  • 逃生出口:“如果发现 X 为真,请立即停止并报告,而不是自行发挥。”

最后编写 plans/README.md,其中包含推荐的执行顺序、计划之间的依赖关系以及一个可由执行模型更新的状态列。

调用变体

  • 裸调用 → 执行上述完整工作流程。
  • quick / deep(在调用中的任何位置)→ 审计的努力级别;请参见阶段 2 中的表格。可与所有变体组合:quick security, deep --issues。默认值为 standard。
  • 带焦点参数(例如 security、perf、tests)→ 执行侦察,然后仅审计该类别,并制定计划。
  • branch → 仅审计当前工作分支的更改:范围 = 自与默认分支合并基准以来变更的文件(git diff --name-only $(git merge-base origin/<default> HEAD)..HEAD)加上它们的直接导入者/调用者。轻量侦察,所有类别,通常无子代理。将每个发现标记为 introduced(由此分支引入)或 pre-existing(在已触发的文件中存在)——表格将它们分开;不要将遗留债务归咎于该分支,但确实要说明它构建在什么基础之上。如果当前在默认分支或与默认分支没有区别,请说明情况并提供完整的审计。
  • next (或 features、roadmap) → 执行侦察,然后仅审计方向类别,并更深入:4–6 个有根据的建议,每个都附带证据、利弊权衡和粗略的工作量估计。被选中的建议将成为设计/探索计划,而不是构建万事计划。
  • plan <描述> → 跳过审计;用户已经知道他们想要什么。执行侦察,只调查足够的信息以恰当地指定它,然后编写一个计划。如果描述过于模糊而无法诚实地指定,请首先尝试通过代码库本身解决每个歧义;剩下的才变成向用户提出的问题——一次只问一个,每个都附带一个推荐答案。
  • review-plan <文件> → 对照模板的标准评审 plans/ 中已有的计划,并对其进行收紧。如果你在同一会话中编写了该计划,还让一个全新上下文的子代理冷读该计划并报告歧义——自我批评会遗漏你根据自己的上下文填补的空白,而执行者没有这些上下文。
  • execute <计划> → 将一个更便宜的执行子代理调度到一个计划上(隔离的 worktree),然后像技术主管一样审查其 diff——重新运行完成标准、检查范围、阅读代码——并给出裁决。需要能够在一个隔离的 worktree 中生成子代理的宿主代理;如果你的代理不能,请说明情况,并改为将计划交给手动执行。在首次调度前阅读 references/closing-the-loop.md。
  • reconcile → 处理自上次会话以来发生的事情:验证已完成的计划,调查受阻的计划,刷新已漂移的待办事项,移除无效的发现。请参见 references/closing-the-loop.md。
  • --issues(任何计划调用上的修饰符)→ 也通过 gh 将每个已编写的计划发布为一个 GitHub issue,URL 记录在计划和索引中。仅在显式标志下使用。请参见 references/closing-the-loop.md。

输出风格

你是在提供建议,而不是推销。用证据直白地陈述发现,诚实地标示不确定性,并倾向于给出“不值得做”的裁决而非凑数。一份简短但高置信度、高杠杆率的计划列表胜过一份冗长的列表。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing accessible design patterns.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Build modern, composable, and accessible React UI components following the components.build specification. Use when creating, reviewing, or refactoring component libraries, design systems, or any reusable UI components. Triggers on tasks involving component APIs, composition patterns, accessibility, styling systems, or TypeScript props.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

相关技能