neckbeard

neckbeard

一种有纪律的软件交付运行模式。它不扮演任何角色，而是让 Agent 稳定地做好六件事：明确变更范围，在设计前了解真实系统，选择最小的安全干预，按阶段执行，记录证据，并在证据不足时停止或升级处理。

这个名字是在调侃“Markdown 文件里的 10 倍开发者”这一套路。其核心恰恰与这种套路相反：这里的成效要靠可观察的结果和范围明确的主张来证明，而不是靠人设来宣称。

何时加载

当请求涉及一项非简单的软件变更时，加载 neckbeard——例如诊断 Bug、构建功能、重构、审查或验证发布——并且你需要一种有明确边界、关注阶段的方式，让任务得以妥善完成。

何时不使用

不要在以下情况加载：

• 只有一个事实性问题或查询（直接回答）。
• 一行代码即可完成，且约定已充分明确的编辑（直接修改，但仍要在交付边界处验证）。
• 任务已由更具体的技能端到端负责（转到该技能；参见 references/routing-table.md）。

核心循环

每次运行都沿着相同的主线推进。每个阶段的进入条件、所需证据、 退出条件和升级规则详见 references/stages.md。

1. 明确变更约定。 说明用户可见的问题、约束、系统边界、风险和明确的非目标。区分探索权限与修改、发布、部署或合并权限。如果没有充分理由进行变更，就尽早停止，并保留支持这一决定的证据。 模板：templates/change-contract.md。

2. 先探索，再设计。 在提出修复方案之前，检查实际代码仓库、贡献指南、架构、调用方、测试、配置和近期变更。优先采用一手证据（代码、测试、运行时输出、项目文档），而非看似合理的架构叙述。明确说明未经验证的假设和缺失的访问权限。

3. 选择最小且安全的干预方式。 首先复用现有代码和平台能力；然后采用满足已验证约定的最小实现。将“最小差异”视为理解后的结果，而非优化目标。绝不牺牲信任边界验证、数据安全、安全性、无障碍性、可观测性、运维恢复能力或明确要求的行为。记录任何有意设定的上限及其升级触发条件。

   如果生产行为已正确，而工作是针对覆盖率缺口或指定变异添加专门保护，则明确将测试加固请求分类。它是轻量路径的一个子类型，而非普通生产缺陷修复：应使用基线通过／变异失败证据，而不是要求新测试在干净的 main 上失败。加载 references/lightweight-test-hardening.md，了解有界约定和升级触发条件。

4. 按 SDLC 阶段执行。 将工作分配给负责的阶段——探索／需求、设计、实现、验证、交付、学习。如果存在匹配的专家技能，就加载该技能，而不是重新推导其方法（见路由表）。

5. 维护证据记录。 每次非简单运行都应生成一份简明记录，包含：意图、检查过的产物、假设、否决的替代方案、变更的文件、运行的命令／检查、观察到的输出、未经验证的边界，以及回滚／后续跟进触发条件。区分组件检查与端到端检查或生产边界检查。格式和规则： references/evidence-ledger.md。 模板：templates/evidence-ledger.md。

6. 按规则停止并升级处理。 如果任务没有经过验证的必要性、风险／权限边界需要人工介入，或两种实质不同的方法都已失败，就停止并报告。绝不为了坚持执行而升级权限、进行破坏性恢复或无边界地反复尝试变通方案。规则： references/risk-authority-gates.md。

对于异步工作和阶段最终性决策，请使用 references/progress-and-finality.md： 应根据语义进展和已声明的依赖关系进行判断，而非根据经过的时间或重复观察。

变更请求工作（有条件）

当请求属于变更请求——即将产生拉取请求或同等可审查交付物的问题、工单或跟踪请求——上述 6 步核心循环仍适用于每个阶段，但整个执行过程还要遵循规范的 9 阶段变更请求流程：

→ references/journey.md — 接收 → 探索 → 设计 → 规格说明 → 测试计划 → 实施 → 审查 → 就绪 → 授权发布。

该流程增加了关卡、用于跨阶段状态传递的交付包，以及平台生命周期机制（GitHub 或企业平台）。它不会取代核心循环，也不会创建第二个编排器。

以下情况不要加载该流程： 简单修复、重构或审查，且没有问题／工单的处理轨迹。这类工作使用核心循环和下方的阶段参考文档，不涉及该流程的阶段、交付包或关卡。

进行中的工作（有条件）

当请求是继续在其他地方启动的交付工作——例如只完成一半的分支、已采纳的规格说明，或由另一位贡献者启动的变更请求——且不存在交付包时，不要从第 1 阶段重新开始，也不要轻信对已完成工作的叙述性摘要。首先进行位置评估：盘点可观察到的产物，根据阶段退出条件为其评分，生成位置报告（当前步骤、附有证据指针的已满足关卡、剩余检查清单），然后初始化交付包并按正常流程继续。

流程：references/position-assessment.md。仅在接手进行中的工作时加载；新变更请求从第 1 阶段开始，现有交付包则依据 references/delivery-packet.md 决定能否续接。

流程开始前选择路径

在了解当前状态后、创建特定路径的产物前，立即选择交付路径。根据受影响的范围和风险做选择，不要只看行数。

对于测试加固请求，仅当生产行为已经正确、生产代码保持不变、变更仅限于测试或夹具，并且有针对性的确定性检查加上有限的受控弱化足以暴露回归时，才选择轻量路径。记录不变量、干净基线的证据、具名变异和非目标。不要套用普通缺陷修复的要求，要求新增测试在干净的 main 上失败。

对于耗时较长或串行执行的 CI，首次推送前，本地设计、隔离性、针对性测试、定向变异、lint、编译和范围检查都必须通过。冻结候选版本后，再请求一次范围有限的最终审查，或仓库要求的平台审查。审查超时意味着结果不确定，不应因此启动多轮重复审查。实质性变更会使相关验证失效，并要求将替代判定绑定到新的确切提交头。

详细的测试加固规范和升级触发条件见 references/lightweight-test-hardening.md。

定义“完成”的唯一规则

未实际执行声明的验证目标，就不得声称“完成”。如果尚未执行，应如实报告未验证的部分，而不是声称已完成。

单元测试通过不等于已验证交付边界。本地渲染不代表生产环境。说明检查了哪个边界，哪些边界尚未检查。 验证方法：加载目录技能 verification-methodology。

正确理解极简主义

此套件中的极简主义是一种在理解真实流程之后才做出的有条件设计选择，而不是无条件地奉行“行数越少越好”。正确的答案有时是更大规模的变更、新依赖、流程变更，甚至完全不改代码。评估夹具包含专门设计的对抗性案例，确保套件无法靠本能地删除或压缩内容取胜。参见 references/stages.md §3。

路由：组合，而非吞并

neckbeard 负责跨阶段契约——变更契约、证据台账、停止规则和评估协议。它不负责领域方法。阶段有专门技能时，请加载并遵循该技能。包含“改用现有技能”条件的完整表格见 references/routing-table.md。摘要：

阶段 / 需求	加载此目录中的技能，而不是重新推导
利益相关者调研、需求、AC	product-discovery
面向用户的行为、交互、信息架构	product-design-and-ux
正式规范、阶段关卡	spec-driven-development
对现有代码库进行逆向工程	software-architecture-analysis
设计或演进 API / 接口契约	api-design-and-evolution
根因调试	systematic-debugging
安全审查、威胁建模、安全设计	secure-software-engineering
无障碍（WCAG、键盘 / 焦点、错误恢复）	web-accessibility
测试策略、回归测试、CI 质量关卡	qa-methodology
移动应用实现（iOS/Android/Flutter/React Native）	mobile-development
文档 / README / API 参考	technical-documentation
验证结论与证据	verification-methodology
一次运行中的意图契约、工作分类、自主性门控、失败路由	bmad
发布规划、版本管理、流水线晋级、就绪情况、发布或回滚设计	release-engineering
可靠性、事件响应或运维恢复	site-reliability-engineering

如果未安装专门技能，neckbeard 的阶段参考会提供最简备用方法——但请在台账中注明该专门技能缺失。

评估是一项一等交付物

此套件在 eval/ 中提供了一个带版本的评估框架，用于衡量此套件声称能改善的软件开发生命周期结果——正确性、回归安全性、范围纪律、边界验证和诚实呈现不确定性，而非代码行数或回复简洁度。在声称有任何改进之前，请运行公开测试套件，并通过维护者的工作流报告留出集结果。方法说明： references/evaluation.md。

声明政策。 所有性能声明都必须限定于经过评估的模型、框架、代码库、任务类别和日期。除非有已发布、可复现的定义和证据，否则不得使用“10 倍开发者”“始终”“最佳”或任何全局性能声明。代码行数只能作为诊断元数据出现，绝不能作为成功的替代指标。

文件映射

路径	加载时机
references/stages.md	进入任何 SDLC 阶段时；定义各阶段的进入条件、证据、退出条件和升级处理
references/evidence-ledger.md	创建或审计台账时；定义必填字段和边界规则
references/risk-authority-gates.md	任何变更、部署、合并或破坏性操作之前；以及停止或升级处理时
references/routing-table.md	判断当前阶段是否由某个专家技能负责时
references/journey.md	仅用于变更请求工作——将产出 PR 或同等可审查交付物的问题／工单／请求。定义从受理到发布的 9 个阶段、关卡和路径。若简单修复、重构或审查没有问题／工单流程，则不加载（此类工作使用上方的核心循环）。
references/lightweight-test-hardening.md	针对已正确的生产行为，仅添加测试回归保护：基线通过／变异体失败证据、隔离性、推送前定稿、有界审查和升级触发条件。
references/lifecycle.md	仅用于变更请求工作——平台操作机制（GitHub 参考模式或企业模式），用于受理、提交、CI／审查监控和授权发布。若简单修复、重构或审查没有问题／工单流程，则不加载。
references/delivery-packet.md	仅用于变更请求工作——在变更请求流程的各阶段传递状态，或在上下文边界之后恢复工作；定义数据包字段、制品归属、生命周期状态和可恢复性。若简单修复、重构或审查没有问题／工单流程，则不加载。
references/position-assessment.md	仅用于进行中的工作——继续在其他地方启动且没有交付数据包的交付工作：制品清单、退出条件评分、进度报告、数据包初始化。
references/tracker-discovery.md	变更请求受理时——检测工作项所在的跟踪系统，并将跟踪器操作路由至匹配的目录工具技能；确保流程用语不依赖特定跟踪器。
references/evaluation.md	设计、运行或报告评估时
templates/	变更契约、决策记录、证据台账、验证计划、评估报告；以及 templates/delivery-packet.md——可填写的数据包，仅用于变更请求工作（不适用于没有问题流程的简单修复／重构／审查）
eval/	任务架构、评分标准、基线协议、夹具、运行器