Back to Details

using-entire

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Entire

使用Entire

Your default when exploring or understanding code should be: read the recorded intent, don't guess.
Entire checkpoints capture the prompts, transcripts, and decisions behind every agent-driven change. When you need to understand why code exists or how a module evolved, look up the checkpoint history first. Only fall back to inference from code structure when no history is available — and label that explicitly.
在探索或理解代码时，你的默认原则应该是：读取已记录的意图，而非主观猜测。
Entire检查点会捕获每次由Agent驱动的变更背后的提示词、对话记录和决策过程。当你需要理解代码存在的原因或模块的演变过程时，请先查看检查点历史。只有在没有历史记录可用时，才退而求其次从代码结构进行推理——并且要明确标注这一点。

When This Skill Activates

本技能的激活场景

Use this skill whenever the task involves:
  • Exploring or understanding an unfamiliar module or file
  • Preparing to refactor, extend, or debug code you didn't write
  • Answering "why is this like this?" or "what was the intent?"
  • Doing pre-work research before making changes
  • Any codebase exploration where historical context would help
Do not use this skill for simple, well-understood edits where you already have full context (e.g. "add a comment to line 5").
在以下任务场景中使用本技能：
  • 探索或理解不熟悉的模块或文件
  • 准备重构、扩展或调试他人编写的代码
  • 解答“为什么代码是这样的？”或“当初的意图是什么？”这类问题
  • 在进行代码变更前开展前置调研
  • 任何需要历史上下文辅助的代码库探索工作
请勿在你已完全掌握上下文的简单、易懂的编辑任务中使用本技能（例如：“给第5行添加注释”）。

First Step: Check Repository Status

第一步：检查仓库状态

Before diving into specific lookups, check whether Entire is available and the repository has checkpoint history:
bash
entire status
This tells you whether Entire is enabled, which git hooks are installed, whether the metadata branch is initialized, and any active sessions on the current branch.
在深入进行具体查询前，先确认Entire是否可用以及仓库是否有检查点历史：
bash
entire status
该命令会告知你Entire是否已启用、安装了哪些git钩子、元数据分支是否已初始化，以及当前分支上的活跃会话情况。

Scenario Routing

场景路由

When this skill activates, determine which sub-skill best fits the user's need:
ScenarioTypical user expressionsDelegate to
Code block provenance"why is this like this" / "wtf is going on" / "what happened at src/auth.ts:42" / "tell me why this changed"
what-happened
Find prior work"has anyone done X before" / "search past work for rate limiting" / "find the previous implementation"
search
Recall a task playbook"have we done this before" / "recall how we did X" / "how did we do this last time"
recall
Replay feature history"replay <feature>" / "walk me through how X was built" / "show me the journey of Y"
replay
Teach a repo topic"teach me <topic>" / "how does <topic> work in this repo" / "give me a lesson on X"
teach
Understand original intent"explain this function" / "explain parseConfig" / "what was the intent behind src/auth.ts"
explain
Generate a dispatch / summary"summarize recent work" / "generate a dispatch" / "what was accomplished this week"run 
entire dispatch
directly
Code review with intent context"review these changes" / "review this branch" / "audit before merging"
review
Hand off to another agent"hand off this session" / "continue in another agent" / "pick up the codex session"
session-handoff
Convert session to skill"turn this into a skill" / "make a skill from this session"
session-to-skill
Link session to other repos"link session to other repos" / "attach session to the foo repo"
session-crosslink
General exploration"understand this module" / "explore how auth works" / "help me understand the codebase"(self — see below)
If the scenario clearly maps to a sub-skill, delegate entirely to that skill's workflow. Do not duplicate their steps here.
激活本技能后，判断哪个子技能最符合用户需求：
场景典型用户表述委托至
代码块溯源“为什么代码是这样的” / “这到底怎么回事” / “src/auth.ts:42处发生了什么” / “告诉我这段代码为什么变更”
what-happened
查找过往工作“之前有人做过X吗” / “搜索过往关于限流的工作” / “找到之前的实现方案”
search
调取任务手册“我们之前做过类似的事吗” / “回忆一下我们是怎么做X的” / “上次我们是怎么处理这个的”
recall
回放功能历史“回放<功能>的开发过程” / “带我了解X是如何构建的” / “展示Y的开发历程”
replay
讲解仓库主题“教我<主题>相关内容” / “这个仓库里<主题>是如何工作的” / “给我讲解一下X”
teach
理解原始意图“解释这个函数” / “解释parseConfig” / “src/auth.ts的设计意图是什么”
explain
生成调度/总结“总结近期工作” / “生成调度报告” / “这周完成了哪些工作”直接运行 
entire dispatch
结合意图上下文的代码评审“评审这些变更” / “评审这个分支” / “合并前做审计”
review
交接至其他Agent“交接当前会话” / 在其他Agent中继续” / “接管codex会话”
session-handoff
将会话转换为技能“把这个会话变成技能” / “从这个会话创建一个技能”
session-to-skill
将会话关联至其他仓库“将会话关联到其他仓库” / “将会话附加到foo仓库”
session-crosslink
通用探索“理解这个模块” / “探索认证系统的工作原理” / “帮我理解这个代码库”(自行处理——见下文)
如果场景明确匹配某个子技能，请完全委托给该子技能的工作流程，不要在此处重复其步骤。

General Exploration Flow

通用探索流程

When no specific sub-skill fits — e.g. the user asks to "understand this module" or "explore how auth works" — use this flow:
  1. Identify key files in the target area (entry points, main types, core functions).
  2. Check for checkpoint coverage on each key file:
bash
git log --format='%H %s' -5 -- <file>
Look for 
Entire-Checkpoint:
trailers in the commit bodies:
bash
git log --format='%H %b' -5 -- <file> | grep -B1 'Entire-Checkpoint:'
  1. Read intent for covered commits — extract the checkpoint ID from the trailer, then use JSON output for non-interactive consumption:
bash
entire explain --checkpoint <checkpoint-id> --json --no-pager
If you only have a commit hash (not a checkpoint ID), use:
bash
entire explain --commit <sha> --no-pager
  1. Synthesize: combine the recorded intent (from checkpoints) with the current code structure to build a comprehensive understanding.
  2. Report your findings, clearly distinguishing:
    • Facts backed by checkpoint transcripts (label as "recorded intent")
    • Observations inferred from code alone (label as "inferred from code")
当没有特定子技能匹配时——例如用户要求“理解这个模块”或“探索认证系统的工作原理”——请遵循以下流程：
  1. 识别目标区域的关键文件（入口文件、主要类型定义、核心函数）。
  2. 检查每个关键文件的检查点覆盖情况：
bash
git log --format='%H %s' -5 -- <file>
在提交信息体中查找
Entire-Checkpoint:
标记：
bash
git log --format='%H %b' -5 -- <file> | grep -B1 'Entire-Checkpoint:'
  1. 读取已覆盖提交的意图——从标记中提取检查点ID，然后使用JSON输出以支持非交互式使用：
bash
entire explain --checkpoint <checkpoint-id> --json --no-pager
如果你只有提交哈希值（而非检查点ID），请使用：
bash
entire explain --commit <sha> --no-pager
  1. 综合分析：将检查点中的已记录意图与当前代码结构相结合，构建全面的理解。
  2. 汇报结果，明确区分以下内容：
    • 由检查点对话记录支持的事实（标注为“已记录意图”）
    • 仅从代码中推断出的观察结果（标注为“从代码推断”）

AI Agent Usage Notes

AI Agent使用注意事项

When running Entire commands from an agent subprocess:
  • Always pass 
    --json
     for commands that support it and might prompt interactively. 
    --json
    implies non-interactive output.
  • Always pass 
    --no-pager
     to prevent pager activation in subprocess contexts.
  • Always specify 
    --checkpoint <id>
    or 
    --commit <sha>
     for 
    entire explain
    — without a locator, the command falls back to an interactive picker.
从Agent子进程运行Entire命令时：
  • 始终传递
    --json
    参数    ：对于支持该参数且可能触发交互式提示的命令，
    --json
    意味着非交互式输出。
  • 始终传递
    --no-pager
    参数    ：防止在子进程环境中激活分页器。
  • 对于
    entire explain
    命令，始终指定
    --checkpoint <id>
    或
    --commit <sha>
    ：如果没有定位符，命令会退回到交互式选择器。

When No Checkpoints Exist

无检查点记录的情况

If the target code predates Entire or has no checkpoint coverage:
  1. Say explicitly: "No Entire checkpoint history is available for this code."
  2. Proceed with standard code understanding (read source, check git log, trace call sites).
  3. Label all explanations as "inferred from code — not backed by recorded intent."
  4. If the user wants deeper history, suggest 
    search
    with related keywords — there may be checkpoints on related work even if the specific file isn't directly covered.
如果目标代码早于Entire的使用时间或没有检查点覆盖：
  1. 明确告知用户：“此代码没有可用的Entire检查点历史记录。”
  2. 继续使用标准的代码理解方式（阅读源代码、查看git日志、追踪调用站点）。
  3. 将所有解释标注为“从代码推断——无已记录意图支持”。
  4. 如果用户需要更深入的历史记录，建议使用
    search
    并搭配相关关键词——即使特定文件没有直接覆盖，相关工作可能存在检查点记录。

Transparency Principle

透明性原则

Always make it clear whether your answer comes from:
  • Checkpoint-backed history — you read the actual session transcript and know the developer's stated intent
  • Code inference — you analyzed the code structure and are reasoning about probable intent
Never present inferred intent as if it were recorded fact. The core value of this workflow is that distinction.
始终明确说明你的答案来源：
  • 检查点支持的历史记录——你读取了实际的会话记录，了解开发者明确表述的意图
  • 代码推理——你分析了代码结构，对可能的意图进行推理
绝不能将推断的意图当作已记录的事实呈现。本工作流的核心价值就在于这种区分。

References

参考资料

For a deeper understanding of Entire's capabilities beyond what the sub-skills cover, consult these resources:
  • CLI help: run 
    entire help
    to see all available commands and flags
  • Documentation: https://docs.entire.io/llms.txt — AI-friendly documentation index following the llms.txt standard, designed to be consumed directly by LLMs and coding agents
如需了解子技能未覆盖的Entire更多功能，请参考以下资源：