guidelines-advisor

guidelines-advisor 技能概览

guidelines-advisor 是一款围绕 Trail of Bits 安全开发指南构建的智能合约开发顾问。它能把代码库转化为可执行的工程建议：更清晰的文档、更合理的架构决策、可升级性审查、实现质量检查、坑点识别、依赖审查，以及测试覆盖建议。

谁应该使用 guidelines-advisor

如果你在做 Solidity 或其他智能合约项目，并且需要结构化审查，而不是一段泛泛的提示词回复，那么就该用 guidelines-advisor。它尤其适合技术写作者、协议工程师、审计人员，以及正在准备内部规格说明或评审记录的团队。

它最擅长什么

当你需要的是对仓库本身进行有引导的评估时，guidelines-advisor 最有优势：每个模块做什么、哪些假设没有写清、升级模式是否有文档、测试或依赖还能怎么改进。它的重点不是重写代码，而是产出足以支持决策的系统分析。

什么时候特别适合用

当你的真实工作是解释、评估或记录一个合约系统，而且需要足够严谨，能支撑评审、交接或更安全的迭代时，就选 guidelines-advisor。对于 guidelines-advisor for Technical Writing 这类工作流，它也很合适：输出要是清楚的英文、具备架构意识，并且紧扣代码库本身。

如何使用 guidelines-advisor 技能

安装并加载技能

使用以下命令安装：

npx skills add trailofbits/skills --skill guidelines-advisor

在执行 guidelines-advisor install 时，请确认你指向的是 trailofbits/skills 仓库，以及 plugins/building-secure-contracts/skills/guidelines-advisor 路径。安装完成后，先从 SKILL.md 开始，再阅读配套资源。

先读这些文件

想最快上手，先预览：

• SKILL.md：作用范围和工作流
• resources/ASSESSMENT_AREAS.md：审查清单
• resources/DELIVERABLES.md：预期输出
• resources/EXAMPLE_REPORT.md：完整分析报告的样子

这些文件展示了这个技能实际会产出什么，这一点比仓库名本身更重要。

给技能完整输入

最好的 guidelines-advisor usage 是先给出一个具体目标，而不是模糊需求。好的输入通常包括项目类型、发生了什么变化、希望评估什么，以及有哪些约束。

更好的提示词：

Analyze this Solidity protocol repo for documentation gaps, upgradeability risks, dependency issues, and test coverage weaknesses. Focus on components that affect user funds and upgrade paths. Summarize findings in plain English and suggest concrete next steps.

较弱的提示词：

Review this repo.

把它当作工作流，而不是一次性提问

一个实用的 guidelines-advisor guide 可以这样安排：

1. 先让它给出系统概览。
2. 再请求架构、可升级性和实现审查。
3. 最后让它结合仓库的实际结构，补充文档缺口和测试改进建议。

如果仓库没有升级机制，或者没有链下组件，要一开始就说明。这能避免浪费分析，也能让输出始终贴着实际情况。

guidelines-advisor 技能常见问题

guidelines-advisor 只适用于 Solidity 吗？

不是，但它对 Solidity 和智能合约系统最有价值。仓库里最强的指导内容是围绕安全合约开发展开的，因此对非合约项目的收益可能会小一些。

它和普通提示词有什么不同？

普通提示词也可以要求审查，但 guidelines-advisor 提供的是可复用的框架：发现、文档生成、架构分析和实现审查。这个结构能减少试错，让不同仓库之间的输出更容易比较。

它适合新手吗？

适合，只要你想要的是对合约代码库的引导式解释。你不需要提前掌握每一条安全开发规则，但你需要一个真实仓库和一个明确目标。对新手来说，最有价值的是让它先输出通俗文档，再列出主要风险。

什么时候不该用它？

如果你只想要快速代码摘要、通用审计清单，或者分析一个没有明显合约架构的项目，就不要用 guidelines-advisor。如果你需要的是一个狭窄的漏洞修复，而不是更广泛的工程审查，它也不是最合适的选择。

如何改进 guidelines-advisor 技能

说明你需要做什么决策

提升 guidelines-advisor 输出的最佳方式，是直接告诉它这次审查是为了什么：入职、文档整理、升级规划、安全加固，还是发布就绪检查。不同目标会改变哪些发现最重要。

指明你关心仓库的哪些部分

高质量输入会点名相关的合约、包或流程，比如代理合约、升级逻辑、手续费路径、代币转账或测试套件。如果你只想用 guidelines-advisor for Technical Writing，就直接说明，并要求它找出缺失解释、含糊假设和更合适的 NatSpec 目标。

要求基于证据的输出

让它把发现绑定到文件路径、函数、模式或缺失文档上。这样结果更容易验证，也能减少空泛评论。例如：

Prioritize undocumented assumptions in contracts/, upgradeability issues in proxy flows, and missing test coverage around external calls.

在第一轮之后继续迭代

第一版输出最适合当地图来用。接着用它提出更窄的问题：“展开可升级性部分”、“按文件列出缺失的 NatSpec”，或者“把这些发现转成文档待办”。这种工作方式，比一口气要所有内容更容易得到更锋利的结果。