Back to Details

explain-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Analyze and Explain Code Functionality

分析并解释代码功能

Available Tools

可用工具

  • Playwright CLI (
    playwright-cli
    ): Use to retrieve external documentation, browse web content, and extract data from documentation sites, forums, and GitHub repositories — especially useful for understanding third-party dependencies and their APIs. Invoke via the 
    /playwright-cli
    skill or run 
    npx playwright-cli
    commands directly.
<EXTREMELY_IMPORTANT>
  • PREFER to use the playwright-cli (refer to playwright-cli skill) OVER web fetch/search tools
    • ALWAYS load the playwright-cli skill before usage with the Skill tool.
    • ALWAYS ASSUME you have the playwright-cli tool installed (if the 
      playwright-cli
      command fails, fallback to 
      npx playwright-cli
      ). </EXTREMELY_IMPORTANT>
  • Playwright CLI (
    playwright-cli
    )：用于获取外部文档、浏览网页内容、从文档站点、论坛和GitHub仓库提取数据——特别适用于理解第三方依赖及其API。你可以通过
    /playwright-cli
    skill调用，或直接运行
    npx playwright-cli
    命令。
<EXTREMELY_IMPORTANT>
  • 优先使用playwright-cli（参考playwright-cli skill）而非网页抓取/搜索工具
    • 使用前必须通过Skill工具加载playwright-cli skill
    • 始终默认你已安装playwright-cli工具（如果
      playwright-cli
      命令运行失败，回退到
      npx playwright-cli
      ） </EXTREMELY_IMPORTANT>

Web Fetch Strategy (token-efficient order)

网页抓取策略（token高效优先级顺序）

When you need external documentation about a library, framework, or API, use the playwright-cli skill (or 
curl
) and apply these techniques in order — stop as soon as you have what you need:
  1. Check 
    /llms.txt
    first     — Many modern docs sites publish an AI-friendly index at 
    /llms.txt
    (spec: llmstxt.org). Try 
    curl https://<site>/llms.txt
    before anything else; it often links directly to the most relevant pages in plain text.
  2. Request Markdown via 
    Accept: text/markdown
     — For any HTML page, try 
    curl <url> -H "Accept: text/markdown"
    first. Sites behind Cloudflare with Markdown for Agents will return pre-converted Markdown (look for 
    content-type: text/markdown
    and the 
    x-markdown-tokens
    header), which is far cheaper than raw HTML.
  3. Fall back to HTML parsing — If neither above yields usable content, navigate the page with 
    playwright-cli
    to extract the rendered DOM, or 
    curl
    the raw HTML and parse locally.
Persist useful findings to 
research/web/
: When you fetch a document worth keeping for future sessions (API references, SDK guides, troubleshooting docs), save it to 
research/web/<YYYY-MM-DD>-<kebab-case-topic>.md
with a short header noting the source URL and fetch date. Check this directory first before re-fetching.
当你需要获取库、框架或API的外部文档时，使用playwright-cli skill（或
curl
）并按以下顺序执行操作——一旦获得所需内容即可停止：
  1. 优先检查
    /llms.txt
    ——许多现代文档站点会在
    /llms.txt
    路径发布对AI友好的索引（规范：llmstxt.org）。在进行任何其他操作前先尝试
    curl https://<site>/llms.txt
    ，它通常会以纯文本形式直接指向最相关的页面。
  2. 通过
    Accept: text/markdown
    请求Markdown格式内容    ——对于任意HTML页面，先尝试执行
    curl <url> -H "Accept: text/markdown"
    。启用了Markdown for Agents的Cloudflare站点会返回预先转换好的Markdown（查找
    content-type: text/markdown
    和
    x-markdown-tokens
    响应头），其成本远低于原始HTML。
  3. 回退到HTML解析——如果以上两种方式都无法获得可用内容，使用
    playwright-cli
    导航到对应页面提取渲染后的DOM，或者用
    curl
    获取原始HTML并在本地解析。
将有用的发现保存到
research/web/
目录： 当你获取到值得在未来会话中留存的文档（API参考、SDK指南、故障排除文档）时，将其保存到
research/web/<YYYY-MM-DD>-<短横线分隔的主题名>.md
，并添加简短页眉注明来源URL和抓取日期。重新抓取前请先检查此目录。

Instructions

操作说明

Follow this systematic approach to explain code: $ARGUMENTS
  1. Code Context Analysis
    • Identify the programming language and framework
    • Understand the broader context and purpose of the code
    • Identify the file location and its role in the project
    • Review related imports, dependencies, and configurations
  2. High-Level Overview
    • Provide a summary of what the code does
    • Explain the main purpose and functionality
    • Identify the problem the code is solving
    • Describe how it fits into the larger system
  3. Code Structure Breakdown
    • Break down the code into logical sections
    • Identify classes, functions, and methods
    • Explain the overall architecture and design patterns
    • Map out data flow and control flow
  4. Line-by-Line Analysis
    • Explain complex or non-obvious lines of code
    • Describe variable declarations and their purposes
    • Explain function calls and their parameters
    • Clarify conditional logic and loops
  5. Algorithm and Logic Explanation
    • Describe the algorithm or approach being used
    • Explain the logic behind complex calculations
    • Break down nested conditions and loops
    • Clarify recursive or asynchronous operations
  6. Data Structures and Types
    • Explain data types and structures being used
    • Describe how data is transformed or processed
    • Explain object relationships and hierarchies
    • Clarify input and output formats
  7. Framework and Library Usage
    • Explain framework-specific patterns and conventions
    • Describe library functions and their purposes
    • Explain API calls and their expected responses
    • Clarify configuration and setup code
    • Use the playwright-cli skill (following the Web Fetch Strategy above) to look up external library documentation when needed
  8. Error Handling and Edge Cases
    • Explain error handling mechanisms
    • Describe exception handling and recovery
    • Identify edge cases being handled
    • Explain validation and defensive programming
  9. Performance Considerations
    • Identify performance-critical sections
    • Explain optimization techniques being used
    • Describe complexity and scalability implications
    • Point out potential bottlenecks or inefficiencies
  10. Security Implications
    • Identify security-related code sections
    • Explain authentication and authorization logic
    • Describe input validation and sanitization
    • Point out potential security vulnerabilities
  11. Testing and Debugging
    • Explain how the code can be tested
    • Identify debugging points and logging
    • Describe mock data or test scenarios
    • Explain test helpers and utilities
    • Use 
      playwright-cli
      to reproduce browser interactions and validate frontend behavior when applicable
  12. Dependencies and Integrations
    • Explain external service integrations
    • Describe database operations and queries
    • Explain API interactions and protocols
    • Clarify third-party library usage
Explanation Format Examples:
For Complex Algorithms:
This function implements a depth-first search algorithm:

1. Line 1-3: Initialize a stack with the starting node and a visited set
2. Line 4-8: Main loop - continue until stack is empty
3. Line 9-11: Pop a node and check if it's the target
4. Line 12-15: Add unvisited neighbors to the stack
5. Line 16: Return null if target not found

Time Complexity: O(V + E) where V is vertices and E is edges
Space Complexity: O(V) for the visited set and stack
For API Integration Code:
This code handles user authentication with a third-party service:

1. Extract credentials from request headers
2. Validate credential format and required fields
3. Make API call to authentication service
4. Handle response and extract user data
5. Create session token and set cookies
6. Return user profile or error response

Error Handling: Catches network errors, invalid credentials, and service unavailability
Security: Uses HTTPS, validates inputs, and sanitizes responses
For Database Operations:
This function performs a complex database query with joins:

1. Build base query with primary table
2. Add LEFT JOIN for related user data
3. Apply WHERE conditions for filtering
4. Add ORDER BY for consistent sorting
5. Implement pagination with LIMIT/OFFSET
6. Execute query and handle potential errors
7. Transform raw results into domain objects

Performance Notes: Uses indexes on filtered columns, implements connection pooling
  1. Common Patterns and Idioms
    • Identify language-specific patterns and idioms
    • Explain design patterns being implemented
    • Describe architectural patterns in use
    • Clarify naming conventions and code style
  2. Potential Improvements
    • Suggest code improvements and optimizations
    • Identify possible refactoring opportunities
    • Point out maintainability concerns
    • Recommend best practices and standards
  3. Related Code and Context
    • Reference related functions and classes
    • Explain how this code interacts with other components
    • Describe the calling context and usage patterns
    • Point to relevant documentation and resources
  4. Debugging and Troubleshooting
    • Explain how to debug issues in this code
    • Identify common failure points
    • Describe logging and monitoring approaches
    • Suggest testing strategies
Language-Specific Considerations:
JavaScript/TypeScript:
  • Explain async/await and Promise handling
  • Describe closure and scope behavior
  • Clarify this binding and arrow functions
  • Explain event handling and callbacks
Python:
  • Explain list comprehensions and generators
  • Describe decorator usage and purpose
  • Clarify context managers and with statements
  • Explain class inheritance and method resolution
Java:
  • Explain generics and type parameters
  • Describe annotation usage and processing
  • Clarify stream operations and lambda expressions
  • Explain exception hierarchy and handling
C#:
  • Explain LINQ queries and expressions
  • Describe async/await and Task handling
  • Clarify delegate and event usage
  • Explain nullable reference types
Go:
  • Explain goroutines and channel usage
  • Describe interface implementation
  • Clarify error handling patterns
  • Explain package structure and imports
Rust:
  • Explain ownership and borrowing
  • Describe lifetime annotations
  • Clarify pattern matching and Option/Result types
  • Explain trait implementations
Remember to:
  • Use clear, non-technical language when possible
  • Provide examples and analogies for complex concepts
  • Structure explanations logically from high-level to detailed
  • Include visual diagrams or flowcharts when helpful
  • Tailor the explanation level to the intended audience
  • Use the playwright-cli skill (following the Web Fetch Strategy above) to look up external library documentation when encountering unfamiliar dependencies, and for live browser inspection when static code analysis is not enough
遵循这套系统化方法来解释代码：$ARGUMENTS
  1. 代码上下文分析
    • 识别编程语言和框架
    • 理解代码的整体上下文和用途
    • 确认文件位置及其在项目中的作用
    • 审查相关导入、依赖和配置
  2. 高层级概览
    • 提供代码功能的摘要说明
    • 解释核心用途和功能
    • 明确代码要解决的问题
    • 描述它在更大系统中的定位
  3. 代码结构拆解
    • 将代码拆解为多个逻辑模块
    • 识别类、函数和方法
    • 解释整体架构和设计模式
    • 梳理数据流和控制流
  4. 逐行分析
    • 解释复杂或非直观的代码行
    • 描述变量声明及其用途
    • 解释函数调用及其参数
    • 阐明条件逻辑和循环
  5. 算法与逻辑说明
    • 描述代码使用的算法或实现思路
    • 解释复杂计算背后的逻辑
    • 拆解嵌套条件和循环
    • 阐明递归或异步操作
  6. 数据结构与类型
    • 解释使用的数据类型和结构
    • 描述数据的转换或处理方式
    • 解释对象关系和层级结构
    • 阐明输入和输出格式
  7. 框架与库使用
    • 解释框架特有的模式和约定
    • 描述库函数及其用途
    • 解释API调用及其预期响应
    • 阐明配置和初始化代码
    • 需要时按照上述网页抓取策略使用playwright-cli skill查询外部库文档
  8. 错误处理与边界场景
    • 解释错误处理机制
    • 描述异常处理和恢复逻辑
    • 识别代码覆盖的边界场景
    • 解释校验和防御性编程逻辑
  9. 性能考量
    • 识别性能关键代码段
    • 解释使用的优化技术
    • 描述复杂度和可扩展性影响
    • 指出潜在的瓶颈或低效点
  10. 安全影响
    • 识别与安全相关的代码段
    • 解释身份验证和授权逻辑
    • 描述输入校验和 sanitization 逻辑
    • 指出潜在的安全漏洞
  11. 测试与调试
    • 解释代码的测试方法
    • 识别调试点和日志记录
    • 描述模拟数据或测试场景
    • 解释测试辅助工具和实用程序
    • 适用场景下使用
      playwright-cli
      复现浏览器交互、验证前端行为
  12. 依赖与集成
    • 解释外部服务集成逻辑
    • 描述数据库操作和查询
    • 解释API交互和协议
    • 阐明第三方库的使用方式
说明格式示例：
复杂算法场景：
This function implements a depth-first search algorithm:

1. Line 1-3: Initialize a stack with the starting node and a visited set
2. Line 4-8: Main loop - continue until stack is empty
3. Line 9-11: Pop a node and check if it's the target
4. Line 12-15: Add unvisited neighbors to the stack
5. Line 16: Return null if target not found

Time Complexity: O(V + E) where V is vertices and E is edges
Space Complexity: O(V) for the visited set and stack
API集成代码场景：
This code handles user authentication with a third-party service:

1. Extract credentials from request headers
2. Validate credential format and required fields
3. Make API call to authentication service
4. Handle response and extract user data
5. Create session token and set cookies
6. Return user profile or error response

Error Handling: Catches network errors, invalid credentials, and service unavailability
Security: Uses HTTPS, validates inputs, and sanitizes responses
数据库操作场景：
This function performs a complex database query with joins:

1. Build base query with primary table
2. Add LEFT JOIN for related user data
3. Apply WHERE conditions for filtering
4. Add ORDER BY for consistent sorting
5. Implement pagination with LIMIT/OFFSET
6. Execute query and handle potential errors
7. Transform raw results into domain objects

Performance Notes: Uses indexes on filtered columns, implements connection pooling
  1. 通用模式与惯用法
    • 识别语言特有的模式和惯用法
    • 解释实现的设计模式
    • 描述使用的架构模式
    • 阐明命名约定和代码风格
  2. 潜在优化点
    • 提出代码改进和优化建议
    • 识别可能的重构机会
    • 指出可维护性相关问题
    • 推荐最佳实践和规范
  3. 关联代码与上下文
    • 引用相关的函数和类
    • 解释该代码与其他组件的交互方式
    • 描述调用上下文和使用模式
    • 指向相关文档和资源
  4. 调试与故障排除
    • 解释如何调试该代码中的问题
    • 识别常见故障点
    • 描述日志记录和监控方案
    • 建议测试策略
特定语言注意事项：
JavaScript/TypeScript：
  • 解释async/await和Promise处理逻辑
  • 描述闭包和作用域行为
  • 阐明this绑定和箭头函数
  • 解释事件处理和回调
Python：
  • 解释列表推导式和生成器
  • 描述装饰器的使用和用途
  • 阐明上下文管理器和with语句
  • 解释类继承和方法解析顺序
Java：
  • 解释泛型和类型参数
  • 描述注解的使用和处理
  • 阐明stream操作和lambda表达式
  • 解释异常层级和处理
C#：
  • 解释LINQ查询和表达式
  • 描述async/await和Task处理
  • 阐明委托和事件的使用
  • 解释可空引用类型
Go：
  • 解释goroutine和channel的使用
  • 描述接口实现
  • 阐明错误处理模式
  • 解释包结构和导入
Rust：
  • 解释所有权和借用
  • 描述生命周期注解
  • 阐明模式匹配和Option/Result类型
  • 解释trait实现
请牢记：
  • 尽可能使用清晰、非技术化的语言
  • 为复杂概念提供示例和类比
  • 按照从高层级到细节的逻辑结构组织说明
  • 有用时添加可视化图表或流程图
  • 根据目标受众调整说明的详细程度
  • 遇到不熟悉的依赖时按照上述网页抓取策略使用playwright-cli skill查询外部库文档，静态代码分析不足时用于实时浏览器检查