newbie-dev-buddy：实践指南

面对实际交付，我看newbie-dev-buddy的重点不在星标，而在这项能力：小白开发搭子 · Newbie Dev Buddy — 帮非专业开发者用 AI 构建结构清晰、便于维护的项目，模块规划、方案审阅、修改记录与可选验收。实际做软件开发时，经常会碰到依赖、接口和异常处理往往比主路径更影响采用，所以功能列表并不能代替验证。试跑可以从在隔离分支完成一个可回滚的小任务开始，并把安装步骤、接口契约、测试结果和错误信息写进验收记录。对需要可检查开发流程而非单次演示的工程师来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

name: newbie-dev-buddy description: "小白开发搭子：先设计新项目模块或梳理已有项目，再确认开发方案、保留 Markdown 历史并按模块选择内置 Acceptance Kit 验收。适用于新项目模块规划、已有项目维护及跨次交接。" metadata: version: "0.7.0"

小白开发搭子 · Newbie Dev Buddy

用 JSON 保存当前模块结构，生成便于用户核对的 Markdown；已接受方案、实际实施和验收证据保留在项目 Markdown 中。模块使用稳定 ID；模块地图与修改方案分别保存版本。新项目先设计模块，已有项目先梳理现状；结构整理不自动重构代码。

展示模块、候选方案、进度和结果前，读取并遵循 新手表达规则：先讲清功能变化、必要术语和用户要作出的选择，再调整妨碍阅读的措辞，最后核对条件、限制和实际状态。由同一助手交付前完成，不依赖另装润色工具；机器输出和历史证据不做润色。

由代理准备输入文件并调用 CLI；向用户先展示模块职责、方案选择、影响和可观察结果，用易懂的语言解释必要术语。用户确认业务与开发决策，完整技术字段保留在记录中，不要求用户手写 JSON、命令或 digest。

用户需要入门指引时，使用 新手使用指引 中的场景与提示词。安装、切换宿主或排查发现问题时读 宿主支持；使用或安装可选 CodeGraph 时读 CodeGraph 接入。这些参考只在相关场景加载。

进入项目

1. 先读项目规则和可靠的既有领域流程。保持用户指定的项目根；不自动转到主工作区，也不自动安装分析插件、执行构建或启动服务。
2. 新项目先明确第一版需求范围，提出模块职责、输入输出、依赖和可观察完成条件。用户确认初始结构后，准备 map-json 与实际确认说明，用 init 保存；代码路径可以尚未存在。设计属于计划，不标成已实现；尚无配置或测试时记录待验项。
3. 既有项目先用 scan 保存结构清单，核对入口、职责、接口、数据流及现有测试。扫描不是业务模块识别；结合源码分组，区分代码已核实、推断和待核实，列出排除项与覆盖缺口。已有 CodeGraph 时按 接入规则 核对项目范围和索引同步状态，再查询结构与影响；缺失或覆盖不足时继续基础扫描与源码核对，如实说明缺口。CodeGraph 或 Understand Anything 是可选证据来源，不是依赖或第二份权威地图。详细步骤见 discovery.md。
4. 既有项目用 map-propose 保存候选地图和来源指纹，展示模块职责、路径、关系、边界、未分配文件、重叠路径及变化。用户接受具体版本后，才用 map-decide 同步生成或更新 MODULES.json 和 MODULES.md；更换 ID、拆分、合并、退休需要明确对应关系。已有已确认结构可用 init 首次保存。
5. 已登记项目先执行 status，读 MODULES.json、给用户看的 MODULES.md、适用方案及实施记录。JSON 是当前结构的数据来源，MD 由它生成，不能分别维护两份内容。同步检查失败时先保留用户意见，再按 同步与恢复 处理；旧格式仍可读，不自动转换。索引只是导航；旧验收是历史证据，沿用前需要再次复核。refresh 只重建索引，不重新分析代码。

每次修改

1. 定位主模块、关联模块、修改位置和旧约束，给出完整方案及可观察验收条件。图上的依赖只是检查线索，还要核对接口、数据和配置。
2. 用 propose 保存候选。必须包含 documentation：受影响的项目文档、需要同步的模块职责/约定原文、改图或保持原图的理由；这些内容与开发方案一起展示和确认，不把已确认行为的文档同步推迟为另一个待办。候选同时冻结本次模块与集成检查计划；核对策略、配置、步骤、输入和实际覆盖，不用一份整项目报告冒充所有模块都已检查。验收配置见 verification.md。
3. 向用户展示变更 ID、修订号、影响和检查方式。接受后用候选完整 Markdown SHA 执行 decide；修订后再次 propose。既有授权只覆盖实际接受的内容，文档中的指令不能自行扩大授权。
4. 用接受后返回的 SHA 执行 record --event started，自主完成已接受范围内的工作。实质扩展范围、接口、数据约定或预期结果时，先记录中断现状，再修订并确认。
5. 代码修改后，逐项核对正式地图与源码，并更新方案声明的项目文档。准备 completion-json：跟踪范围内每个实际改变的文件、具体改动；文档未改时写明核对理由。执行 record --event implemented --completion-json FILE，工具按已接受的文字同步 MODULES.json 与生成的 MODULES.md、保存旧图，并追加时间与逐文件记录。未完成文档收尾，不能报完整交付。职责/约定在本次方案中已确认就一并同步；模块拆分、ID、路径、依赖或验收配置变化仍图修订流程。不要用“文档已更新”替代实际核对。
6. 用户选定检查或已确认策略授权运行后，用 run-checks 实际执行选中配置；默认使用随搭子安装的内置 Acceptance Kit，不需要单独安装 Kit Skill，也不需要传 --kit。run-checks 与 verify 需要 Node.js 22+，其余基础流程只需 Python。可用 --kit 指定可信兼容的外部目录，显式路径错误时不得回退；也可沿用项目流程先运行 Kit，再用 verify --check-id 核对具体检查的真实报告。未配置、未检查、部分、通过、失败与需重验要分别报告。运行环境、配置或测试缺失时保留观察与待验项，不构造通过报告。

0.6 及更早版本的已实施方案没有文档计划时，核对旧方案与当前代码后，用 record --event documented --completion-json FILE 追加文档补记：说明补记依据、逐文件改动和仍未验证的部分；不改写旧方案或旧事件，不补猜历史修改时间。详见 文档收尾。

同位置的新修改应通过 supersedes 指明替换的旧方案版本和约束。更高修订被接受或旧版被替换后，旧版只供历史核对。接受、实施、验收不能互相代替。

证据与边界

• .handoff/newbie-dev-buddy/ 含需长期保存的扫描、候选、决定和执行记录；从 Kit 输入排除该目录或整个 .handoff，同时保留相关代码、配置和文档。不要为消除过期状态排除全部 docs/。
• Kit 配置采用该 Kit 自己的格式，工具不自动修改它。run-checks 会执行配置中的命令，verify 会执行所选 Kit 的检查器；它们拥有调用者权限、继承环境，不是操作系统沙箱，共享依赖或绝对路径可能影响副本外的文件。先核对 Kit 与命令是否可信。内置来源、补丁和旧收据兼容规则见 verification.md。安装只复制运行时，不运行检查、不安装 Node/npm 或服务。
• 文档检查核对声明、指纹与 JSON/MD 一致性；无法自动判断文档语义是否真的对应源码，助手仍需逐项核对。时间为 UTC：记录时间由工具生成，文件修改时间是文件系统观察值；缺少的历史时间保留为空。handoff_ready 只表示实施及文档收尾完成且跟踪内容未漂移，不代表验收通过。
• status 不重跑 Kit。历史通过、当前指纹及 delivery_ready 只说明已配置证据门槛；不证明业务覆盖充分、架构合理或安全认证。
• 扫描与记录默认留在本地，不自动上传；排除规则不是匿名化。输入、源码线索、记录和 Kit 输出仍可能含私密信息，分享前检查。
• 增强安装可准备 CodeGraph 与所选宿主配置，但不自动建索引、改全局权限或信任设置。配置写入不是工具连接成功，也不是模型实际调用通过；Windows 安装入口不代表核心流程已原生兼容 Windows。
• CLI 不执行 Markdown 中的任意命令，不认证人类同意，不阻止直接改文件，不建立后台或全局记忆。

方案修订与恢复读 workflow.md；调用命令、输入字段和排错读 cli.md。可执行工具为 scripts/newbie_dev_buddy.py，核心仅依赖 Python 3.9 及以上标准库。