Back to Details

guidelines-advisor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Guidelines Advisor

指南顾问

Purpose

目标

Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:
  1. Generate documentation and specifications (plain English descriptions, architectural diagrams, code documentation)
  2. Optimize on-chain/off-chain architecture (only if applicable)
  3. Review upgradeability patterns (if your project has upgrades)
  4. Check delegatecall/proxy implementations (if present)
  5. Assess implementation quality (functions, inheritance, events)
  6. Identify common pitfalls
  7. Review dependencies
  8. Evaluate test suite and suggest improvements
Framework: Building Secure Contracts - Development Guidelines
基于Trail of Bits的开发指南，系统性地分析代码库并提供指导：
  1. 生成文档与规范（纯英文描述、架构图、代码文档）
  2. 优化链上/链下架构（仅在适用情况下）
  3. 审查可升级性模式（若项目支持升级）
  4. 检查delegatecall/代理实现（若存在）
  5. 评估实现质量（函数、继承、事件）
  6. 识别常见陷阱
  7. 审查依赖项
  8. 评估测试套件并提出改进建议
框架：Building Secure Contracts - 开发指南

How This Works

工作流程

Phase 1: Discovery & Context

阶段1：发现与上下文梳理

Explores the codebase to understand:
  • Project structure and platform
  • Contract/module files and their purposes
  • Existing documentation
  • Architecture patterns (proxies, upgrades, etc.)
  • Testing setup
  • Dependencies
探索代码库以了解：
  • 项目结构与平台
  • 合约/模块文件及其用途
  • 现有文档
  • 架构模式（代理、升级等）
  • 测试设置
  • 依赖项

Phase 2: Documentation Generation

阶段2：文档生成

Helps create:
  • Plain English system description
  • Architectural diagrams (using Slither printers for Solidity)
  • Code documentation recommendations (NatSpec for Solidity)
协助创建：
  • 纯英文系统描述
  • 架构图（使用Solidity的Slither打印机生成）
  • 代码文档建议（Solidity的NatSpec规范）

Phase 3: Architecture Analysis

阶段3：架构分析

Analyzes:
  • On-chain vs off-chain component distribution (if applicable)
  • Upgradeability approach (if applicable)
  • Delegatecall proxy patterns (if present)
分析：
  • 链上与链下组件分布（若适用）
  • 可升级性方案（若适用）
  • Delegatecall代理模式（若存在）

Phase 4: Implementation Review

阶段4：实现审查

Assesses:
  • Function composition and clarity
  • Inheritance structure
  • Event logging practices
  • Common pitfalls presence
  • Dependencies quality
  • Testing coverage and techniques
评估：
  • 函数组合与清晰度
  • 继承结构
  • 事件日志实践
  • 常见陷阱存在情况
  • 依赖项质量
  • 测试覆盖率与技术

Phase 5: Recommendations

阶段5：建议提供

Provides:
  • Prioritized improvement suggestions
  • Best practice guidance
  • Actionable next steps
提供：
  • 按优先级排序的改进建议
  • 最佳实践指导
  • 可执行的后续步骤

Assessment Areas

评估领域

I analyze 11 comprehensive areas covering all aspects of smart contract development. For detailed criteria, best practices, and specific checks, see ASSESSMENT_AREAS.md.
我会分析涵盖智能合约开发所有方面的11个综合领域。如需详细标准、最佳实践和具体检查项，请查看ASSESSMENT_AREAS.md。

Quick Reference:

快速参考：

  1. Documentation & Specifications
    • Plain English system descriptions
    • Architectural diagrams
    • NatSpec completeness (Solidity)
    • Documentation gaps identification
  2. On-Chain vs Off-Chain Computation
    • Complexity analysis
    • Gas optimization opportunities
    • Verification vs computation patterns
  3. Upgradeability
    • Migration vs upgradeability trade-offs
    • Data separation patterns
    • Upgrade procedure documentation
  4. Delegatecall Proxy Pattern
    • Storage layout consistency
    • Initialization patterns
    • Function shadowing risks
    • Slither upgradeability checks
  5. Function Composition
    • Function size and clarity
    • Logical grouping
    • Modularity assessment
  6. Inheritance
    • Hierarchy depth/width
    • Diamond problem risks
    • Inheritance visualization
  7. Events
    • Critical operation coverage
    • Event naming consistency
    • Indexed parameters
  8. Common Pitfalls
    • Reentrancy patterns
    • Integer overflow/underflow
    • Access control issues
    • Platform-specific vulnerabilities
  9. Dependencies
    • Library quality assessment
    • Version management
    • Dependency manager usage
    • Copied code detection
  10. Testing & Verification
    • Coverage analysis
    • Fuzzing techniques
    • Formal verification
    • CI/CD integration
  11. Platform-Specific Guidance
    • Solidity version recommendations
    • Compiler warning checks
    • Inline assembly warnings
    • Platform-specific tools
For complete details on each area including what I'll check, analyze, and recommend, see ASSESSMENT_AREAS.md.
  1. 文档与规范
    • 纯英文系统描述
    • 架构图
    • Solidity的NatSpec完整性
    • 文档缺口识别
  2. 链上 vs 链下计算
    • 复杂度分析
    • Gas优化机会
    • 验证与计算模式
  3. 可升级性
    • 迁移与可升级性的权衡
    • 数据分离模式
    • 升级流程文档
  4. Delegatecall代理模式
    • 存储布局一致性
    • 初始化模式
    • 函数遮蔽风险
    • Slither可升级性检查
  5. 函数组合
    • 函数大小与清晰度
    • 逻辑分组
    • 模块化评估
  6. 继承
    • 层次深度/广度
    • 菱形问题风险
    • 继承可视化
  7. 事件
    • 关键操作覆盖率
    • 事件命名一致性
    • 索引参数
  8. 常见陷阱
    • 重入模式
    • 整数溢出/下溢
    • 访问控制问题
    • 平台特定漏洞
  9. 依赖项
    • 库质量评估
    • 版本管理
    • 依赖管理器使用情况
    • 复制代码检测
  10. 测试与验证
    • 覆盖率分析
    • 模糊测试技术
    • 形式化验证
    • CI/CD集成
  11. 平台特定指导
    • Solidity版本建议
    • 编译器警告检查
    • 内联汇编警告
    • 平台特定工具
如需每个领域的完整细节，包括我将检查、分析和建议的内容，请查看ASSESSMENT_AREAS.md。

Example Output

示例输出

When the analysis is complete, you'll receive comprehensive guidance covering:
  • System documentation with plain English descriptions
  • Architectural diagrams and documentation gaps
  • Architecture analysis (on-chain/off-chain, upgradeability, proxies)
  • Implementation review (functions, inheritance, events, pitfalls)
  • Dependencies and testing evaluation
  • Prioritized recommendations (CRITICAL, HIGH, MEDIUM, LOW)
  • Overall assessment and path to production
For a complete example analysis report, see EXAMPLE_REPORT.md.
分析完成后，你将收到涵盖以下内容的全面指导：
  • 包含纯英文描述的系统文档
  • 架构图与文档缺口
  • 架构分析（链上/链下、可升级性、代理）
  • 实现审查（函数、继承、事件、陷阱）
  • 依赖项与测试评估
  • 按优先级排序的建议（CRITICAL、HIGH、MEDIUM、LOW）
  • 整体评估与上线路径
如需完整的示例分析报告，请查看EXAMPLE_REPORT.md。

Deliverables

交付成果

I provide four comprehensive deliverable categories:
我会提供四大类全面的交付成果：

1. System Documentation

1. 系统文档

  • Plain English descriptions
  • Architectural diagrams
  • Documentation gaps analysis
  • 纯英文描述
  • 架构图
  • 文档缺口分析

2. Architecture Analysis

2. 架构分析

  • On-chain/off-chain assessment
  • Upgradeability review
  • Proxy pattern security review
  • 链上/链下评估
  • 可升级性审查
  • 代理模式安全审查

3. Implementation Review

3. 实现审查

  • Function composition analysis
  • Inheritance assessment
  • Events coverage
  • Pitfall identification
  • Dependencies evaluation
  • Testing analysis
  • 函数组合分析
  • 继承评估
  • 事件覆盖率
  • 陷阱识别
  • 依赖项评估
  • 测试分析

4. Prioritized Recommendations

4. 按优先级排序的建议

  • CRITICAL (address immediately)
  • HIGH (address before deployment)
  • MEDIUM (address for production quality)
  • LOW (nice to have)
For detailed templates and examples of each deliverable, see DELIVERABLES.md.
  • CRITICAL（立即处理）
  • HIGH（部署前处理）
  • MEDIUM（为达到生产质量处理）
  • LOW（锦上添花）
如需每个交付成果的详细模板和示例，请查看DELIVERABLES.md。

Assessment Process

合理化说明（请勿跳过）

When invoked, I will:
  1. Explore the codebase
    • Identify all contract/module files
    • Find existing documentation
    • Locate test files
    • Check for proxies/upgrades
    • Identify dependencies
  2. Generate documentation
    • Create plain English system description
    • Generate architectural diagrams (if tools available)
    • Identify documentation gaps
  3. Analyze architecture
    • Assess on-chain/off-chain distribution (if applicable)
    • Review upgradeability approach (if applicable)
    • Audit proxy patterns (if present)
  4. Review implementation
    • Analyze functions, inheritance, events
    • Check for common pitfalls
    • Assess dependencies
    • Evaluate testing
  5. Provide recommendations
    • Present findings with file references
    • Ask clarifying questions about design decisions
    • Suggest prioritized improvements
    • Offer actionable next steps
合理化理由错误原因要求操作
"系统很简单，描述已经涵盖所有内容"纯英文描述会遗漏安全关键细节完成全部5个阶段：文档、架构、实现、依赖项、建议
"未检测到升级，跳过可升级性部分"可升级性可能是隐式的（拥有者模式、delegatecall）在声明不适用前，搜索代理模式、delegatecall、存储冲突
"未验证就标注‘不适用’"过早缩小范围会遗漏漏洞在跳过任何指南部分前，通过明确的代码库搜索进行验证
"架构很简单，无需分析"看似明显的架构存在微妙的信任边界分析链上/链下分布、访问控制流、外部依赖项
"常见陷阱不适用于此代码库"每个代码库都存在常见陷阱使用grep/代码搜索系统性检查所有指南中的陷阱
"已有测试，满足测试指南要求"测试存在 ≠ 测试质量达标检查覆盖率、基于属性的测试、集成测试、失败场景
"我可以提供通用最佳实践"通用建议不具备可执行性提供带有文件:行号引用的项目特定发现
"用户从发现结果中知道需要改进什么"没有优先级的发现 = 无行动计划生成带有具体后续步骤的优先级改进路线图

Rationalizations (Do Not Skip)

注意事项

RationalizationWhy It's WrongRequired Action
"System is simple, description covers everything"Plain English descriptions miss security-critical detailsComplete all 5 phases: documentation, architecture, implementation, dependencies, recommendations
"No upgrades detected, skip upgradeability section"Upgradeability can be implicit (ownable patterns, delegatecall)Search for proxy patterns, delegatecall, storage collisions before declaring N/A
"Not applicable" without verificationPremature scope reduction misses vulnerabilitiesVerify with explicit codebase search before skipping any guideline section
"Architecture is straightforward, no analysis needed"Obvious architectures have subtle trust boundariesAnalyze on-chain/off-chain distribution, access control flow, external dependencies
"Common pitfalls don't apply to this codebase"Every codebase has common pitfallsSystematically check all guideline pitfalls with grep/code search
"Tests exist, testing guideline is satisfied"Test existence ≠ test qualityCheck coverage, property-based tests, integration tests, failure cases
"I can provide generic best practices"Generic advice isn't actionableProvide project-specific findings with file:line references
"User knows what to improve from findings"Findings without prioritization = no action planGenerate prioritized improvement roadmap with specific next steps
  • 我只会分析相关部分（若不存在升级，不会凭空编造相关内容）
  • 我会适配你的平台（Solidity、Rust、Cairo等）
  • 我会使用可用工具（Slither等），若工具不可用也可正常工作
  • 我会为所有发现提供文件引用和行号
  • 对于无法从代码中推断的设计决策，我会提出疑问

Notes

准备开始

  • I'll only analyze relevant sections (won't hallucinate about upgrades if not present)
  • I'll adapt to your platform (Solidity, Rust, Cairo, etc.)
  • I'll use available tools (Slither, etc.) but work without them if unavailable
  • I'll provide file references and line numbers for all findings
  • I'll ask questions about design decisions I can't infer from code
我需要的信息：
  • 代码库访问权限
  • 项目目标相关上下文
  • 任何现有文档或规范
  • 部署计划相关信息
让我们使用Trail of Bits的最佳实践分析你的代码库并对其进行改进！

Ready to Begin

—
What I'll need:
  • Access to your codebase
  • Context about your project goals
  • Any existing documentation or specifications
  • Information about deployment plans
Let's analyze your codebase and improve it using Trail of Bits' best practices!
—