just-use-it

上手使用

先使用，最后阅读源代码。

对一个可访问源代码的库、框架、CLI 或开发者工具开展使用优先审计。通过用户可用的接口检验其能力面，然后检查源代码，找出公开能力，以及动手测试遗漏的相关可运行仓库环境。

审计负责体验、覆盖证据和发现项数据包。使用 assess-findings 进行证据资格认定和行动建议，包括在缺失事实可能影响建议时开展有边界的调查。安装其 investigate-with-evidence 依赖项。若任一项不可用，则继续可行的使用测试，并保留尚未评估且注明缺失依赖项的发现项数据包；评估仍待完成。产品修复和跟踪系统写入需要单独授权。协同运行的 $yak-shaving-triage 在已配置的授权范围内负责跟踪系统协调和工作记录捕获；正式发布到跟踪系统仍需另行授权。

按切片优先的方式开展工作。每个执行 Agent 都要完成一个面向用户成果的能力旅程、其差异化变体，以及分配给它的能力组中适用的探索工作。可通过下方委派工作流并发执行独立切片。打开一个入口点或容器只能验证该入口点；不能据此验证其中的能力。

1. 界定范围并隔离

确定目标、目标用户、面向用户的文档，以及测试所需的环境。从请求和工作区推断这些信息；只有在仍存在多个实质不同的目标时才提问。

确定成果范围

遵循用户明确指定的范围。继续执行时，先恢复已选批次及其进度，再选择后续工作。对于普通使用请求，选择一个由若干重要能力组构成的有限批次；这些能力组按项目结构或功能组织，每组包含面向用户成果的旅程。根据主要工作流、记录的深度、未覆盖区域和相关发现来选择；存在有意义的工作时，应选择多个能力组。宣布批次、必要依赖项和延期处理的独立成果。选择有用的批次，不要固定数量或人为拆分能力组。明确要求完整能力面审计时，保留完整范围；较窄的请求则保留其自身边界，包括与 Explore 协同使用时的边界。

在文档研究、使用测试、源代码核对和评估各阶段，都要覆盖该批次。纳入可能改变结论、解释阻碍因素或使证据失效的新检查。将具有独立价值的新成果记录到未来待办中。仅有共享组件不足以成为扩展范围或重查已验证工作的理由。完成情况仅描述已声明的批次；保留更广范围的覆盖图，不要声称整个产品已完成审计。

用户指示变更范围时，须保留此前的覆盖情况以及对源代码和跟踪系统的检查记录。发现吸引人的想法或遇到棘手阻碍，都不能成为悄然缩小批次范围的理由。

确定产物和入口阶段

在开始或恢复审计时，选择或构建审计产物之前，先应用证据时效性与目标选择中的要求，检查源代码、已执行的产物和原始上游版本。此要求既适用于新审计，也适用于有记录的续审。使用所选目标文档中说明的构建版本，而非无关的已安装版本。确认实际运行的可执行文件、导入的包或部署版本后，才能将行为作为证据。观察结论应限于实际运行的内容；源代码对应关系未知时，只会限制源代码归因，不会限制直接观察。若源代码或历史记录检查受限，检查许可范围内的身份元数据，并推迟实现对比；保留不确定性和重新开启检查的条件。 对于日常续测，在选择路线前，先阅读记录约定中相关的已配置工作记录。根据待处理的结果、行为变化和相关证据确定实际使用的优先级，并为新观察留出空间。旧的 Verified 结果只能证明记录中所述制品的情况，不能代表当前版本。没有续测上下文的新审计应从公开用户任务开始。如果用户要求独立体验，应在审计关卡前暂不查看历史发现正文、摘要和跟踪器研究；仅查询配置不必暴露发现。如果已知历史信息，应说明这一限制，不要声称审计完全独立。这些选择会改变来源信息和路线顺序，但不会改变声明的结果范围。

规划各轮之前，先确认入口阶段。对于续测或已知问题复核，恢复现有覆盖范围、证据来源、评估负责人以及源代码／跟踪器的访问状态。延续尚未通过的关卡，并且仅刷新与请求范围相关的证据；将该状态告知使用、Assess 和 Yak 工作人员。新工作人员和临时项目应继承这些来源信息。只要相关关卡仍未通过，以下阶段开启步骤就适用；已开放的源代码调查和结果协调可以与剩余的使用测试并行进行。实际公开使用仍是行为证据的来源。

对于初始的盲源代码审计，在前两轮中，不得查看行为实现源代码和目标项目的问题跟踪器。遵循仓库说明，并阅读启动工具所需的公开文档和入口点元数据。如果文档所述的启动路径失败，应先记录该结果，再使用运行所需的元数据使目标可运行；在源代码审查阶段开始前，仍不得查看实现代码。

源代码封闭意味着对行为保持盲态，而非忽视安全。只检查判断执行是否安全所需的最低限度安装钩子、启动脚本、权限和外部影响，不得据此推断产品行为。如果安全执行需要扩大源代码检查范围，应披露无法维持盲测顺序，而不要声称遵循了 Usage-First Audit。

对于 CLI、公开 API 或软件包的使用，在进行使用者环境设置、安装或首次调用之前（包括帮助和版本探测），请先阅读参考资料／程序化体验。

对于判断取决于自动选择的项目、工作区或配置来源，或取决于工作负载大小或处理范围的用户流程，请在执行前阅读上下文与工作负载检查。

当缺少必需的运行时、编译器工具链、SDK、系统软件包、容器运行时或类似前置条件时，在安装任何内容或放弃相关能力之前，请先阅读参考资料／前置条件。

在进行高成本执行或处理不确定的工作负载之前，请先阅读资源控制。将其总预算应用于直接工作、工作人员及其后代；文件系统隔离无法限制内存使用。

优先使用可丢弃状态：

• 如果用户已明确打开浏览器或标签页并要求使用，应优先选择该现有会话，而不是另建会话。
• 保持目标检出中的受跟踪文件不变。视情况使用现有的安全运行实例、可丢弃副本或工作树，或者位于目标之外的使用者工作区。
• 记录审计创建的每个临时路径、进程、服务端和浏览器上下文，以便在完成、失败或中断时准确清理这些资源。
• 将外部影响限制在可丢弃项目、测试数据或沙盒内。保留所有现有授权检查点；无法安全测试的能力应标记为 Blocked。 完成条件： 明确结果范围与排除项、目标及其运行时对应关系或不确定性、公开起始材料、入口阶段与继承的门槛、浏览器选择、隔离边界、清理目标，以及所有已知的前置决策。

2. 梳理文档记录的功能面

对于初始审计，根据公开文档构建 Capability Surface，不读取行为实现源代码，并将每项范围内的文档所述功能状态标记为 Not Exercised；将已知的范围外功能保留为结果范围下的排除项。对于后续审计，针对请求的范围更新现有 Coverage Ledger，并刷新需要更新的证据。

按项目结构或功能组织 Capability Groups。在每个组内，沿着跨越必要组件边界的完整用户结果旅程进行梳理。根据产品的主要任务和相关的既有覆盖情况排列所选组。从精简的 Coverage Ledger 开始，列出每个已知的 Capability Group、其预期结果、接口和模式、当前状态以及下一步操作。

在初始门槛仍处于关闭状态时，保持实现源代码和目标问题跟踪器关闭。源代码关闭意味着对行为一无所知：公开文档以及安全启动所需的入口点元数据仍可使用。

完成条件： 每项范围内的功能都归入某个用户结果组，其保留或待完成的覆盖情况均明确，并已确定下一个 Vertical Capability Slice。

3. 完成纵向切片

每个切片开始前，根据执行者能否在有限上下文中独立推进、其资源状态能否得到控制，以及委派带来的收益是否值得承担交接与集成成本，选择执行者。将紧密耦合的调查工作留给当前负责人；如果独立任务受益于单独的上下文，则使用新的工作者。边界不明确时，由当前负责人继续推进，直到边界明确。在分配工作、并发运行切片或更改负责人之前，请阅读执行协调。主 Agent 执行时也遵循相同的旅程和证据要求。

受指派的工作者在其切片内遵循此技能；无需重新启动整个审计或再次委派。在初始的盲源代码阶段，所有 Agent 都必须保持实现源代码和目标问题跟踪器关闭。后续指派应沿用审计既定的源代码／跟踪器阶段及其来源信息，而不是重新开始盲审流程。对于每个受指派的 Capability Group：

如果该组使用交互式 UI，请在控制 UI 前阅读 references/ui-experience.md。在为切片指定终态之前，先完成其 UI Journey Gate；该参考文档定义了必要的观察项，以及排除项和 Blocked 路径。

1. 严格按照其文档说明的 Capability Journey，通过公共接口操作，直至产生可观察到的用户结果。
2. 执行一项判别性变化：只更改一个输入、状态、模式或恢复条件，并应产生可观察到的不同结果。如果该能力不存在实质性变化，请明确记录排除理由。
3. 阅读 references/exploration-lenses.md，然后在当前 Capability Group 内自由探索。构建一个小型、以能力为核心的矩阵。当实际结果和实质性变化均有证据支持、具体发现已得到足以支撑判断的调查或明确标记了未解决的依赖项，并且能够说明下一个有价值的不确定点或排除项时，即完成该组。发现或未发现 bug 都不是完成标准；只有在完整根因会影响分类、补救措施、责任归属或范围时，才需要查明完整根因。
4. 将新发现的公共能力添加到 Capability Surface。将服务于当前结果的能力保留在当前切片中；依据结果范围对可独立产生价值的结果进行分类，将范围内的结果作为新的 Not Exercised 分组添加，并将其余结果记录为排除项。
5. 在首次指定 Verified 状态之前，阅读 references/verification-traces.md。只有具备完整 Verification Trace 的能力才能标记为 Verified。一旦行为可能构成发现，就立即阅读 references/finding-packets.md，保留其证据，并提交协调员进行早期评估。在评估人员根据当前来源/跟踪器阶段审查数据包期间，继续使用该能力。
6. 为切片中的每项能力指定终态并记录其证据；委派的执行者应将其交回主 Agent。主 Agent 检查证据并更新 Coverage Ledger，然后依据相同的执行标准选择下一项任务。Verified、Finding、Observed 和 Blocked 都是使用环节的终态；Observed 表示已执行该流程，但对问题或改进的判断尚未完成。评估状态与使用完成状态彼此独立；Not Exercised 仍表示待处理。

保存每个已完成分组的探索深度和证据，然后在现有授权范围内自动继续下一个选定分组。只要已知的批次内能力仍可行，就继续处理已完成的切片。进度更新应以切片边界为准；Partial Audit 描述的是覆盖不完整，而不是结束任务的理由。当用户要求停止或缩小范围，或缺少必要前提、访问权限或用户输入，导致无法继续取得有意义的范围内进展时，结束未完成的审计。如果某项能力处于 Blocked 状态，仍要继续其他可行工作。结束时，保留剩余覆盖范围和恢复条件。在初始跟踪器核对前临时暂停，不会打开该关卡；已打开的关卡则保持打开状态。如果中断导致本次运行结束，且已知范围内能力仍为 Not Exercised，则保留当前切片和下一步操作，冻结已完成的 Finding Packet，并报告 Partial Audit。独立运行的录制工作流可以核对这些已冻结的数据包；审计工作在读取跟踪器历史记录（包括后续恢复记录）后进行，属于有跟踪器信息支持的审计，而非对行为一无所知的审计。

即使通过未记录的更正方式使实现正常工作，文档错误仍属于 Finding。不要利用运行元数据或源代码知识，暗中补救文档所述流程。 完成条件： 每项无需查看源码即可发现的范围内能力都有终止状态；每个实质适用的探索视角都已通过实际路径进行检验，或被明确排除；每项 Verified 能力都有一条 Verification Trace；并且每个已选分组都符合上述深度标准。此完成声明不涵盖未来独立分组。

4. 与源码对照

当实现源码仍处于未开放状态时，主 Agent 应在所需的动手体验切片及其证据均已落实，且符合前述使用阶段完成标准后，再打开源码。向评估工作者宣布这一状态转换；在追踪器自身的门槛开放前，其历史记录仍保持关闭状态。尽可能将源码与已体验的产物对应起来；来自其他修订版本的线索应标明限定条件，直到在相应产物上实际体验为止。

检查与结果范围及其必要依赖相关的公开导出、路由、命令、标志、功能注册、示例和测试，查找尚未覆盖的已发布公开能力。按照相同的范围边界，将新发现的独立结果分类。除非标记为内部、仅供测试或尚未发布，否则将已发布的导出项、可执行文件、路由或浏览器全局对象视为公开；仅有隐藏的帮助条目不足以证明其为私有。明确报告尚未解决的公开意图。

阅读 references/repository-environments.md，以发现能够展现其他能力体验路径、组件状态或集成的可运行仓库环境。这些环境可提供有用的体验，但其本身不一定是面向终端用户发布的内容。应将这些环境的证据范围与其所代表的产品路径区分开来。

将通过源码发现的能力和相关环境对应到现有覆盖、合理的排除项或新分配的使用任务。按照相同的执行标准为新切片选择执行者，并记录其源码发现来源。源码检查提供线索；实际执行提供使用证据。如果发现或源码证据暴露出先前覆盖的局限，请重新审视相关覆盖。评估工作者现在可以在各自分配的建议范围内调查依赖源码的问题，同时独立使用探索仍可继续。

通过使用或明确排除，落实所有范围内经源码确认的公开入口点和相关环境后，冻结独立观察数据包并开放审计对账门槛。协同进行的记录工作流可对账该批次，并将证据交还给指定评估者。没有 Yak 时，评估者可以执行其方法允许的有界只读追踪器检查。读取追踪器历史会使后续工作带有追踪器信息；新工作者无法恢复盲态来源。

开放该门槛后，也可以抽查公开问题历史，作为覆盖范围的最终校准。重新体验相关公开路径；在此过程中首次遇到的行为应视为已知问题复现，而非独立发现。

完成条件： 通过源码发现的覆盖范围均已落实，所有使用切片都具有终止状态，并且数据包来源和对账资格均已明确。若评估仍在等待某项已指明的前置条件，则不妨碍使用阶段转换。

5. 报告并清理

使用发现交接，在最终报告前收集评估结果。以对话形式返回审计报告，包含：

• 预期目标、实际测试的制品或实例，以及环境；
• 声明的结果范围、排除项，以及覆盖范围账本中每项范围内能力的状态；
• 每项 Verified 能力的简要验证追踪；
• 已评估的发现、改进机会、未解决的观察结果和排除的声明，以及它们的证据和各自独立的行动建议；
• 对于部分运行，列出 Blocked 和 Not Exercised 能力；
• 由单独激活的记录工作流返回的跟踪器链接或标识符，适用于已复用记录或已成功发布的更改；以及
• 清理结果。

如果任何已知的范围内能力仍为 Not Exercised，则将结果称为 部分审计。指出已完成的垂直能力切片和剩余工作。否则，报告已完成声明范围，并清楚列出其排除项；只有全面覆盖审计才能声称整个能力面已完成。

除非用户明确要求仓库制品，否则报告应保持对话形式。用户要求保存时，使用其指定的确切目标位置和仓库惯例。正式跟踪器发布不属于此技能范围。经授权的工作记录更新可通过共享记录契约保留数据包和评估，无需完整的审计报告制品；如果缺少目标位置，必须明确说明该持久化仍待处理。在身份匹配期间保留独立审计门槛，包括在获准访问历史记录前写入观察结果的情形。

结束审计前，停止或退役所有审计工作器，并收集其资源状态。删除临时状态前，将所需证据移入对话、用户要求的报告或经独立授权的记录工作流。根据共享记录契约保留覆盖深度和后续操作，包括部分进度或受资源中断影响的进度。然后仅删除确切的临时路径，并仅停止为本次审计创建的进程、服务、标签页或浏览器上下文。保留用户拥有的浏览器状态。报告每项清理失败，并注明残留路径或运行中的资源。

**完成条件：**报告中的覆盖范围声明与账本一致；每个数据包均已评估，或明确说明证据缺失或依赖项限制；并且每条临时路径和每项运行中的资源均已移除，或已报告为残留状态。