GitNexus 实施级工程计划文档模板解析compact/full 双形态、证据标签与 13 节结构规范【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus本文围绕 GitNexus 仓库中 gitnexus-plan 技能 的规范核心——plan-template.md——系统讲解GitNexus Engineering Plan文档的标准结构它如何用 compact/full 两种形态承载不同深度的工作、如何在每个论断上打上[verified]等证据标签、又如何通过 §11 的机器可读上下文包把一次调查结果无损传递给后续实施 Agent。读完本文你将掌握该模板的逐节语义、80 行硬上限的取舍逻辑、evidence provenance证据溯源schema 2 的生成与校验方式以及编写/发布计划文档的全部硬性约束。模板在工作流中的定位一份可直接开工的交付物在 GitNexus 的 Agent 体系中gitnexus-plan是一个只做计划、绝不实现的深度规划技能其产物是一份计划文档 一个机器可读的 implementation context pack。规范规定产物必须写入仓库内形如docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-slug.md的路径。这份模板定义了计划文档本身的结构契约计划文档告诉人类或实施 Agent任务是什么、当前行为与架构如何、图与语句级 PDG 发现了什么、改哪里、按什么顺序改、怎么测、何时算完成§11 的上下文包见 context-pack.md则让跟随实施方如gitnexus-work或任意执行器无需重做调查即可开始工作。在仓库中该技能存在多份字节一致或同步的副本.claude/skills/gitnexus-plan/Claude Code 使用、随 CLI 分发的 gitnexus/skills/gitnexus-plan/以及插件版 gitnexus-claude-plugin/skills/gitnexus-plan/其中 scripts/evidence-provenance.mjs 由gitnexus-plan与gitnexus-work携带字节完全一致的副本保证规划方与执行方对同一棵工作树计算出相同的哈希。模板开篇即明确两条总则由Phase 0 的任务类别决定使用compact窄/默认工作还是full深度工作形态调用中的form参数可以覆盖类别默认值无论哪种形态所有仓库产物一律使用 repo 相对路径即相对于目标仓库根目录的路径而非文档自身所在目录。形态入口任务类别先于篇幅决定深度SKILL.md 的 Phase 0 依据任务类别给出姿态深度 · 形态 · 工具预算 · 新鲜度策略可大致归纳为任务类别默认形态特点Bug fix局部compact1~2 个主符号impact_depth1约 15 次调用Featurecompact默认参数约 30 次调用Refactor / 共享 API 变更full强制 impactimpact_depth3约 45 次调用Performance / Securityfull附带性能/安全 PDG 模式依赖升级 / 迁移compact以 impact 兼容性为主并发 / 事务类full控制流 状态变更 PDG 焦点测试改进 / 文档compact通常无需 impact 或 PDG 通道架构变更 / spikefull最宽泛无调用次数上限depth:narrow|default|deep、form:compact|full、freshness:strict|accept、impact_depth、pdg_data_depth、pdg_control_depth等均以key:value形式写在调用中如/gitnexus-plan depth:deep impact_depth:3 ...显式参数优先于类别姿态。当交互会话未带深度信号时会向上提问一次Quick / Standard / DeepHeadless 运行则直接套用类别姿态。Compact 形态只保留承重章节的最小骨架Compact 模板以相同的 evidence header 开头随后只保留承重小节且要求在标题中保留 § 编号——这是为了让gitnexus-work的 § 引用可以稳定解析。# GitNexus Engineering Plan Task: one line Evidence verified at commit sha; GitNexus index .... Evidence provenance schema 2; global dirty digest sha256; cited-path manifest count sorted entries; exact generated plan path excluded. ## Objective (§1) ## Current Behaviour (§2–3) — ≤10 lines, architecture folded in ## Findings (§4–5) — only load-bearing, each tagged tool-named ## Proposed Changes (§6) ## Implementation Sequence (§7) — risks inline as step notes ## Test Strategy (§8) ## Implementation Context (§11) — the mini-pack (see context-pack.md) ## Assumptions and Open Questions (§12) ## Definition of Done (§13)Compact 形态的核心约束80 行硬上限不含 §11 包。一旦超限不是去注水正文而是说明任务被误分类了——重新归类为 full 而非溢出§2–3 合并描述当前行为控制在 10 行以内架构信息折叠其中§4–5 只保留承重发现每条都要打标签并注明来源工具被裁掉但仍重要的事实在 §12 以一行记录绝不写成填充式散文。Full 形态全部 13 节一节都不能静默缺席Full 形态用于深度工作重构、安全、性能、并发、架构类。它要求填满每一个小节若某节对当前任务确实为空例如仓库没有索引 PDG 层保留标题并在一行内说明原因绝不静默删除。论断标签Claim tagging让证据可审计Full 形态要求给每个承重论断打上证据类别标签未打标签的文字只是叙述narrative不是证据[verified]——在固定 commit 上读过源码确认[graph]——来自 GitNexus/PDG 输出未经源码确认[inferred]——有证据支撑的推理[assumed]——未经证实必须同时出现在 §12。模板全文如下# GitNexus Engineering Plan Task: one line Evidence verified at commit HEAD sha; GitNexus index fresh | refreshed this session (--index-only [--pdg]) | N commits behind, refresh skipped: reason | not used. Evidence provenance schema 2; global dirty digest sha256; cited-path manifest count sorted entries; exact generated plan path excluded. ## 1. Objective A concise description of the requested outcome. ## 2. Current Behaviour Describe the current implementation and execution path. Include the most relevant symbols, files, and statement-level observations. ## 3. Relevant Architecture Explain the involved modules, boundaries, dependencies, and established patterns. ## 4. GitNexus Findings Summarise: - primary symbols; - callers and callees; - impact radius; - related implementations; - related tests; - important cross-module relationships. ## 5. Statement-Level PDG Findings For each critical symbol, explain: - relevant statements; - control dependencies; - data dependencies; - state mutations; - error branches; - side effects; - ordering constraints; - planning implications. Do not paste an unfiltered graph dump. ## 6. Proposed Changes For every proposed change include: - file; - symbol; - exact responsibility; - intended behavioural change; - dependencies; - constraints; - implementation notes. ## 7. Implementation Sequence Provide an ordered sequence of implementation steps. Each step must be independently actionable. ## 8. Test Strategy Describe: - tests to add; - tests to update; - edge cases; - failure paths; - regression coverage; - integration boundaries; - relevant verification commands. ## 9. Risk and Impact Analysis Include: - high-risk symbols; - downstream consumers; - compatibility concerns; - performance concerns; - concurrency or transaction risks; - migration risks; - observability requirements. ## 10. Files Expected to Change | File | Symbols | Reason | | ---- | ------- | ------ | ## 11. Reusable Implementation Context The machine-readable context pack — see context-pack.md. Its mandatory evidence_provenance field carries the full pinned commit, canonical repository-wide dirty digest, and sorted cited-path manifest. ## 12. Assumptions and Open Questions Clearly separate assumptions from confirmed facts. Explicitly-deferred follow-up suggestions (adjacent work the task didnt ask for) land here too. ## 13. Definition of Done Concrete, testable completion criteria.逐节职责可归纳如下§1 是一句话目标§2/§3 描述现状与架构含最相关符号、文件与语句级观察§4 汇总 GitNexus 图调查主符号、调用者/被调者、影响半径、相关实现与测试、跨模块关系§5 是核心函数的语句级 PDG 切片控制依赖、数据依赖、状态变更、错误分支、副作用、顺序约束、规划影响但严禁倾倒未经筛选的图谱转储§6 对每个改动给出文件、符号、精确职责、预期行为变化、依赖、约束与实现注记§7 是按依赖排序、每步可独立执行的实现序列§8 列出新增/更新的测试、边界与失败路径、回归覆盖、集成边界与可运行的验证命令§9 做风险与影响分析高风险符号、下游消费者、兼容性、性能、并发/事务、迁移、可观测性§10 用表格列出预计变更文件§11 内嵌机器可读上下文包§12 区分假设与确认事实并收纳被显式推迟的后续建议§13 给出可测试的完成标准。13 节从何而来与技能阶段一一对应模板的章节并非随意拼凑而是与 SKILL.md 的调查阶段严格对应模板章节对应阶段header 的 commit / freshness 字段Phase 1 锚定与新鲜度门控§4 GitNexus FindingsPhase 2 图导航阶梯query → context → impact/trace → cypher§5 PDG FindingsPhase 3 语句级 PDG 切片见 pdg-slice.md§2/§3/§6 的verify before assertPhase 4 定向源码验证§11 上下文包 header 溯源Phase 5 组合前的 evidence_provenance 快照调查过程中的一切中间信息先记入上下文账本context-ledger.md每次 GitNexus 调用和源码读取都要登记回答了什么规划问题账本同时强制符号预算默认 5 主符号 / 20 相关符号并钉住 HEAD 与脏工作树证据。账本本身绝不原样发布计划和上下文包由它蒸馏而成。贯穿两形态的证据溯源契约evidence provenance schema 2计划能否被信任地执行取决于执行方能否区分commit 漂移与工作树脏状态。因此两种形态的 header 都要求携带 schema 2 的证据溯源信息其规范性字节契约定义在 evidence-provenance.md可执行实现是 scripts/evidence-provenance.mjs约 2366 行零 npm 依赖。它的职责被严格限定为三个子命令命令参数作用snapshot--repo、--generated-plan、--schema-version 2、可重复的--cited path输出完整的evidence_provenanceJSON含全局脏摘要 排序的引用路径清单需原样拷贝进文档禁止在正文或 shell 中重建read-plan--repo、--generated-plan读取既有计划的唯一受支持方式返回带规范generated_plan_path、bytes_read、精确plan_bytes_base64与plan_digestsha256:hex的 JSON receiptwrite-plan--repo、--generated-plan、--replace、--expected-plan-path、--expected-plan-digest从 stdin 接收完整 UTF-8 计划最大 16 MiB原子发布初始计划绝不传--replaceDeepen 才允许典型调用在目标仓库根目录node skill-dir/scripts/evidence-provenance.mjs snapshot \ --repo $PWD \ --schema-version 2 \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --cited src/one.ts \ --cited test/one.test.tsschema 2 的摘要算法是带版本号的NUL 分隔 UTF-8 记录流的 SHA-256global_dirty_digest覆盖全部脏路径不止被引用的路径每条记录含 path、state、各层对象类型、所有可得层摘要与重命名的两个端点cited_path_manifest则按规范化后的 repo 相对路径排序逐路径记录object_kindhead/index/worktree/untracked 各层regular | symlink | gitlink | directory | absent、statestaged | unstaged | untracked | deleted | renamed | mixed | absent及各层摘要。摘要唯一排除的是本次生成的计划自身路径因此写计划不会使自己证据失效。schema 1 被视为 legacy 并被显式拒绝需要保守地按 schema 2 重新锚定。文件名与路径白名单生成计划的路径必须是docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-kebab-slug.md含合法日历日期snapshot 排除与写入不能指向.git、源码、配置或任意 repo 文件。为兼容历史文档read-plan额外接受匹配docs/plans/*gitnexus-plan*.md的规范化文件但该读取兼容性不会放宽写入器的白名单。路径必须为 NFC 规范化的 POSIX repo 相对路径拒绝 NUL、反斜杠、绝对路径、空组件与./..任何非法 UTF-8、非 NFC 名称、未合并索引阶段、符号链接父目录穿越等都会 fail closed。原子无覆盖写盘与平台差异发布机制刻意不 spawn 解释器、不加载原生代码用link(2)原子发布目标名已被占用时返回EEXIST且不跟随符号链接目标——这与renameat2(RENAME_NOREPLACE)/renameatx_np(RENAME_EXCL)等价经fs.linkSync在所有受支持平台可用。写前在持握的目录描述符旁创建随机独占临时文件写后先哈希再发布发布后再次以O_NOFOLLOW复验路径绑定 inode 与摘要。平台差异也被明确承认而非掩盖Linux 上每个名字都经由/proc/self/fd/fd/child这类 magic link 解析父目录在检查与使用之间被重命名也无法劫持操作——竞态不可能发生macOS 没有等价机制改为对链上每个目录持握打开的描述符并在每一步前后反复证明链仍指向同一组 inode因此是检测而非预防——父目录在窗口内被替换会被紧随其后的检查发现并中止且未写入任何字节。两种平台都没有发布字节逃逸校验的路径。Deepen 的--replace仅接受已存在的普通文件并强制--expected-plan-path与--expected-plan-digest必须来自同一次read-planreceipt旧计划会先被原子移动到 Git 管理目录下随机命名的gitnexus-plan-backups/备份文件经git rev-parse --git-path gitnexus-plan-backups/name解析随后新计划才以同样的无覆盖原语发布。§11 机器可读上下文包执行方免重调查的接口§11 的完整规范在 context-pack.md。compact 形态只发mini-pack仅task_summary、evidence_provenance、files_to_modify、tests、verification_commands、pdg_constraints仅当切片真正运行过、assumptions、open_questions、avoidfull 形态输出全部字段。两种形态的字段语义一致且evidence_provenance均为强制字段。gitnexus-work把缺失的可选字段视为空而非错误。implementation_context: task_summary: acceptance_criteria: [] evidence_provenance: schema_version: 2 head_commit: # full commit SHA that source citations pin to generated_plan_path: global_dirty_digest: algorithm: sha256 canonicalization: gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records value: # digest only; do not embed the whole dirty-path manifest cited_path_manifest: # sorted by normalized repo-relative path - path: object_kind: # per layer: regular | symlink | gitlink | directory | absent head: index: worktree: untracked: state: clean | staged | unstaged | untracked | deleted | renamed | mixed | absent rename_from: null rename_to: null head_digest: sha256:hex | absent index_digest: sha256:hex | absent worktree_digest: sha256:hex | absent untracked_digest: sha256:hex | absent primary_symbols: [] related_symbols: [] # relationship: CALLS / IMPORTS / EXTENDS / test-of / ... execution_path: [] # ordered prose steps, from §2/§5 pdg_constraints: [] # from the PDG slice; empty note if no layer architectural_patterns: [] files_to_modify: [] tests: [] # existing file to update, or new path to create verification_commands: [] risks: [] assumptions: [] open_questions: [] avoid: - Do not repeat full repository discovery - Do not replace established patterns without evidence该包明确不得包含完整文件、仓库级原始脏路径清单、大段 GitNexus 原始响应、未过滤的 PDG 转储、重复的代码摘录应引用file:line而非重贴、以及被包装成事实的臆测实现细节。稳定性契约同样严格字段名是gitnexus-work消费的接口——可以自由新增字段但不得重命名或改变既有字段用途。assumptions与avoid是承重字段执行方把 assumptions 当作执行前需低成本复验的事项把 avoid 当作硬约束。evidence_provenance也是承重字段其版本、全局摘要与排序的引用路径清单使执行方能区分 commit 漂移与 staged/unstaged/untracked/deleted/renamed/mixed/absent 等各类工作树证据缺少它或使用 schema 1 的 legacy 包一律要求保守地按 schema 2 重新锚定绝不被解释为干净工作树。执行方必须经 helper 的read-plan读取计划并要求包内generated_plan_path与 receipt 的规范路径逐字节相等。Composition notes成文前的硬性纪律模板末尾的组合注记是该文档最容易被忽略、却决定计划可信度的一节逐条解读如下组合前先发快照立刻输出evidence_provenance.schema_version、完整 HEAD commit、规范global_dirty_digest与按规范化 repo 相对路径排序的cited_path_manifest含对象类型、重命名端点与各层摘要只从全局摘要中排除生成的计划路径只经 helper 生成溯源记录按 evidence-provenance.md 调用 scripts/evidence-provenance.mjs 并原样拷贝 schema-2 JSON禁止在散文或 shell 中重建规范记录只经write-plan发布先在仓库外/内存中完成 UTF-8 文档再以 stdin 传给 helper。初次计划不得覆盖既有文件Deepen 通过write-plan --replace --expected-plan-path path-from-read-plan --expected-plan-digest digest-from-read-plan重写同一相对路径旧计划在 receipt 的prior_plan_backup_git_path中留档。两个期望值必须来自同一份receiptDeepen 必须先用read-plan加载并绑定该规范路径与原始字节§2/§5 引用上限源码摘录每处最多max_snippet_lines默认 30行且仅当该摘录真正承载论证时才引用§4 每条发现都注明工具调用tool 关键参数并在计划倚重时附一行结果原文——这是工具论断事后可审计的关键过期索引或 fallback 模式的发现必须显式标注§6 只能引用 ledger 标记为source_verified的符号——出现在 Proposed Changes 中的符号必须经过源码验证§7 按依赖排序且每步独立可行执行者可以在任一步后停下而树仍自洽。凡是会改动 fingerprint、golden、recorded baseline 的步骤只在序列最后一步一次性再生成——CI 只裁决 tip每步刷新会搅乱中间提交并在后续步骤落地时再次漂移§8 必须点名真实存在的测试文件新增测试给出具体场景清单input → action → expected outcome验证命令必须真实存在且可运行优先采用自带前置钩子/构建的 npm/CI 脚本形式而非直接调用底层二进制§9 必须覆盖 impact pass 报告的每一个直接depth-1依赖者。与其余规划工具链的关系这份模板处于一套自洽文档体系的末端全链路文件如下文件作用.claude/skills/gitnexus-plan/SKILL.md技能主流程Phase 0~5、硬规则、配置旋钮、Deepen 模式与 Fallback 模式references/plan-template.md本文所述的 13 节计划文档模板references/context-pack.md§11 上下文包 schema 与稳定性契约references/context-ledger.md调查账本 schema 与反重复读取规则references/evidence-provenance.md证据溯源 schema 2 的规范性字节契约references/pdg-slice.md语句级 PDG 切片的工具、收录标准与安全/性能模式scripts/evidence-provenance.mjssnapshot 序列化器 描述符锚定的计划读写器模板同样决定了Deepen 模式的演进路径/gitnexus-plan deepen plan-path先经read-plan读取并绑定既有计划的规范路径与摘要随后重跑完整 Phase 1含 freshness 门控并在推进 pin 之前重新锚定——变更、改名、删除或新消失的引用路径都要先重读或降级论断再逐条把[graph]/[inferred]提升为[verified]补齐 §7 中已由gitnexus-work落地的步骤最后用write-plan --replace重写同一规范文件。何时该用哪种形态一个判断范式模板给出了一条清晰的升级判据compact 计划若超过 80 行不含 §11 包说明任务被误分类应重新归类为 full 而非任其溢出。反过来深度工作若仍用 compact就意味着承重章节被压缩到不可执行。此外turn economy本身就是可交付物——SKILL.md 以仓库 eval/workflow_bench 中一次两行改动用了 63 轮的实测为反面案例强调按类别调用预算执行、预算耗尽就把未决问题写进 §12 而非继续深挖因为执行方本就廉价复验。换言之模板的意义不在于把计划写厚而在于让每个论断可溯源、每步可执行、每处空白被显式声明——这正是 GitNexus Engineering Plan 文档模板最核心的设计哲学。【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
