Back to Details

decodie-explain

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Decodie — Explain Mode

Decodie — 代码解释模式

Walk a developer through a specific piece of code they have selected or pasted. Produces a conversational, human-readable explanation directly in the chat.
This mode is read-only with respect to source code and ephemeral by default — nothing is written to 
.decodie/
unless the user explicitly asks to save.
引导开发者理解他们选定或粘贴的特定代码片段。直接在聊天中生成对话式、易于人类阅读的解释。
此模式对源代码只读且默认仅临时存在——除非用户明确要求保存，否则不会写入.decodie/目录。

Scope and Inputs

适用范围与输入内容

Operates on code the user has selected, pasted, or pointed at. Does not scan projects or discover files.
If no code has been provided, ask the user to share the code they want explained.
仅处理用户选定、粘贴或指向的代码，不会扫描项目或自动发现文件。
若用户未提供代码，请提示其分享需要解释的代码内容。

Output Format

输出格式

Produce the explanation as conversational markdown in the chat. Do not write to disk unless asked.
以对话式Markdown格式在聊天中生成解释，除非用户要求，否则不得写入磁盘。

1. Summary

1. 概述

A short paragraph (2-3 sentences) describing what the code does at a high level.
用一小段文字（2-3句话）从宏观层面描述代码的功能。

2. Detailed Breakdowns

2. 详细拆解

For each complex or non-obvious section:
  • A fenced code block with the code excerpt
  • An explanation of what it does, why, and any patterns/idioms it uses
  • The pattern name if applicable (e.g., "guard clause", "memoization")
Aim for 2-5 breakdowns depending on complexity. Skip trivial code.
针对每个复杂或非直观的代码段：
  • 包含代码片段的围栏代码块
  • 解释其功能、设计意图以及所使用的模式/惯用写法
  • 若适用，标注对应的模式名称（例如："守卫子句"、"记忆化"）
根据代码复杂度，拆解2-5个部分即可，跳过无意义的简单代码。

3. Potential Issues

3. 潜在问题

List bugs, security concerns, performance problems, edge cases. For each:
  • severity: 
    info
    , 
    warning
    , or 
    error
  • description: what is wrong and when it manifests
  • suggestion: how to address it
If you find no issues, say so plainly.
列出可能存在的bug、安全隐患、性能问题及边缘场景。每个问题需包含：
  • 严重程度：
    info
    （信息）、
    warning
    （警告）或
    error
    （错误）
  • 描述：问题内容及触发场景
  • 建议：解决方法
若未发现问题，请直接说明。

4. Improvements

4. 改进建议

Refactoring opportunities, modern alternatives, readability wins. For each:
  • description: the proposed change
  • rationale: why it helps
提供重构方案、现代替代写法、可读性优化建议。每个建议需包含：
  • 描述：拟修改的内容
  • 理由：修改的益处

5. Key Concepts

5. 核心概念

Bulleted list of core patterns, principles, and language features to take away.
以项目符号列表形式列出需掌握的核心模式、原则及语言特性。

Saving an Explanation (on explicit request only)

保存解释（仅在用户明确要求时执行）

Only persist when the user explicitly requests it.
仅当用户明确提出保存请求时，才持久化数据。

Setup

设置步骤

  1. Check if 
    .decodie/
    exists at the project root. If not, create it:
    • .decodie/index.json
      with 
      { "version": "1.0", "project": "<directory-name>", "entries": [] }
    • .decodie/config.json
      with default preferences
    • .decodie/sessions/
      directory
  2. Determine session ID. Find the highest 
    NNN
    for today in 
    .decodie/sessions/
    matching 
    explain-YYYY-MM-DD-NNN
    , then increment.
  1. 检查项目根目录是否存在.decodie/，若不存在则创建：
    • .decodie/index.json
      ，内容为
      { "version": "1.0", "project": "<directory-name>", "entries": [] }
    • .decodie/config.json
      ，包含默认偏好设置
    • .decodie/sessions/
      目录
  2. 确定会话ID：在.decodie/sessions/中找到当日最高编号的
    explain-YYYY-MM-DD-NNN
    格式文件，将编号NNN加1作为新会话ID。

Session entry fields

会话条目字段

Write to the session file with:
  • code_snippet
    : The selected code as provided.
  • explanation
    : The Summary section.
  • alternatives_considered
    : Alternative approaches if relevant; empty string otherwise.
  • key_concepts
    : Array of core concepts.
  • breakdowns
    : Array of 
    { code_excerpt, explanation, pattern? }
    .
  • issues
    : Array of 
    { severity, description, suggestion }
    .
  • improvements
    : Array of 
    { description, rationale }
    .
将会话内容写入文件，需包含以下字段：
  • code_snippet
    ：用户提供的选定代码
  • explanation
    ：概述部分的内容
  • alternatives_considered
    ：相关替代方案（若无则为空字符串）
  • key_concepts
    ：核心概念数组
  • breakdowns
    ：包含
    { code_excerpt, explanation, pattern? }
    的数组
  • issues
    ：包含
    { severity, description, suggestion }
    的数组
  • improvements
    ：包含
    { description, rationale }
    的数组

Index entry

索引条目

  • id
    : Format: 
    entry-{unix-timestamp}-{random-4-hex-chars}
  • decision_type
    : 
    "explanation"
  • content_file
    : relative path to session file, e.g. 
    sessions/explain-2026-03-27-001.json
If the code came from an identifiable file, include a reference with content-based anchoring:
  • file
     — relative path from project root
  • anchor
     — function signature, class declaration, or distinctive code block
  • anchor_hash
     — first 8 hex chars of SHA-256 of the anchor text (
    echo -n "<anchor_text>" | shasum -a 256 | cut -c1-8
    )
If pasted without a known origin, 
references
may be empty.
  • id
    ：格式为
    entry-{unix-timestamp}-{random-4-hex-chars}
  • decision_type
    ：
    "explanation"
  • content_file
    ：会话文件的相对路径，例如
    sessions/explain-2026-03-27-001.json
若代码来自可识别的文件，需添加基于内容的锚定引用：
  • file
     — 相对于项目根目录的路径
  • anchor
     — 函数签名、类声明或独特代码块
  • anchor_hash
     — 锚定文本SHA-256值的前8位十六进制字符（执行命令：
    echo -n "<anchor_text>" | shasum -a 256 | cut -c1-8
    ）
若代码为无来源的粘贴内容，
references
字段可留空。

Session Closure

会话结束

Set 
timestamp_end
, write a brief 
summary
, and confirm: "Saved explanation as entry 
<id>
in session 
<session_id>
."
设置
timestamp_end
，写入简短
summary
，并确认："已将解释保存为会话
<session_id>
中的条目
<id>
。"

Data Format

数据格式

See references/schema.md for the full 
.decodie/
data format.
完整的.decodie/数据格式请参考references/schema.md。

Important Notes

重要注意事项

  • Ephemeral unless asked. Only write to 
    .decodie/
    when the user explicitly requests persistence.
  • Calibrate depth to the code. A five-line utility does not need five breakdowns.
  • Be honest about uncertainty. If code is ambiguous, say so.
  • 默认临时存在，按需保存：仅当用户明确要求持久化时，才写入.decodie/目录。
  • 根据代码复杂度调整解释深度：五行以内的工具类代码无需五个拆解部分。
  • 诚实说明不确定性：若代码存在歧义，请直接告知用户。