StrayMark — 设计原则
版本： 0.2.2（实证注解 + 面向公开可读性的编辑修订：对 Sentinel 工件的内部引用已通用化；在前向词汇中将 Plan → Charter 重命名） 日期： 2026-05-02 作者： Jose Villaseñor Montfort — StrangeDaysTech 目的： 以紧凑形式阐明产品哲学，作为设计决策的参考依据，以及对不相契合的功能说"不"的判断标准。
本文档为何存在
软件产品会随时间漂移，朝着推动力最强的激励方向。如果压力是营收，它们就漂向能卖钱的功能。如果压力是采用率，它们就漂向能病毒式传播的功能。如果压力是竞争，它们就漂向与最显眼竞品的对等。这每一种漂移单独看都是理性的，合在一起却是破坏性的：产品失去其原有形态，沦为市场上又一个被平均化了的点。
本文档存在的意义，是让 StrayMark 拥有一个明确的锚点。未来的决策必须能够对照这些原则进行检验。一项违反某条原则的功能仍可能是好主意，但需要一次有意识的对话——明确哪条原则正在被放宽、为什么。文档的存在并不保证纪律；它所迫使产生的有意识发问，才能保证。
原则按层级排序：当两条发生冲突时，靠前者胜出。
0.2 版 — 实证注解。 本版本纳入了第一次以证据应力测试这些原则后获得的经验：在一个真实采用方项目（Sentinel — 一个 Go 后端系统）上的六个执行周期，包括 Charter 格式的三次迭代（v1 → v2 → v3）以及每周期两次双外部审计。各原则的注解集中于实验直接演练的三条（#6、#9、#12）；十二条原则的层级与措辞不变。详细证据见 straymark-thesis-validation.md（出于历史参考目的保存在 docs/decisions/proposals/ 中）。
1. 工具服务于手艺，而非产品自身
StrayMark 的存在是为了让与 AI Agent 协作的工程师产出令自己自豪的工作。这是最终的衡量标准。任何以降低用户工作质量为代价、改善采用、留存或营收指标的功能，都是违反这条根本原则的功能。
实践上，这意味着决策时所问的不是*"这能让产品更壮大吗？"，而是"这能帮工程师做出更好的工程吗？"*。两个问题有时一致，有时不一致。当它们分歧时，前者胜出。
2. 主要用户是编排 Agent 的资深工程师
不是工程副总裁。不是 CISO。不是合规官。主要用户是技术判断力强、借助 AI Agent 推进自己单独无法实际承担的项目、并需要外化的认知纪律以防止 Agent 引入系统性混乱的工程师。
功能为这个人设计。流程为这个人优化。文档为这个人撰写。当其他人（合规官、经理、审计员）最终使用产品时，他们是在一个首先尊重工程师的基础之上使用。颠倒这一层级，是开发者工具产品变质的最常见原因。
3. 严格开源，核心毫无附加条件
Framework、CLI 与 TUI 现在是、并将永远是宽松许可证下的开源。OSS 中没有为推动付费而被阉割的功能。没有强制遥测。没有完整使用所必需的账户要求。没有"社区版"在核心能力上劣于"企业版"的设定。
当未来存在商业层（Cloud、托管、服务）时，它必须提供真正附加的价值，而不是把 OSS 中本应包含的功能搬走、人为制造需求。诚实的 open-core 与 bait-and-switch 式 open-core 的区别，就在于对"什么是附加价值"与"什么是工具本身"是否诚实。
4. 法规合规是副作用，而非产品目标
ISO/IEC 42001、EU AI Act、NIST AI RMF、GDPR 是为文档化提供结构的有用框架。StrayMark 将其作为可选层来支持，因为它们对需要的用户有价值。但产品本身不是"一款合规工具"。产品是一款工程工具，它作为副产品产出与那些框架兼容的证据。
这一区分至关重要，因为合规购买者与使用工具的工程师有不同的需求。当产品被定位为合规工具时，设计决策会偏向合规购买者，从而损害工程师的工作流。把合规当作副作用，能够保护主流程的质量。
5. Schema 驱动优先于功能驱动
产品的核心实体（Stage Closure Bundle、Charter、Document）首先以严格版本化的正式 schema 定义。功能基于这些 schema 构建。这带来三个结构性收益：允许多个实现共存而无需互相协调；让演化变得受控且可逆；并迫使在实现之前先思考契约。
实践后果是：schema 的破坏性变更稀少且经过深思；schema 是产品的一等文档；任何需要违反 schema 的功能必须先提议 schema 的演化。
6. 认知纪律优先于原始生产力
StrayMark 不与那些承诺*"用 AI 把代码写快 10 倍"*的工具竞争。它若与什么对抗，对抗的是 AI 快速产出的代码在严肃项目中所制造的混乱。重要的不是 Agent 的原始速度，而是所产出系统的持续质量。
这意味着增加合理摩擦的功能（验证、关卡、文档要求、规划前的预备工作）是可接受的，有时甚至是可取的。承诺以牺牲 Agent 推理质量为代价去除摩擦的功能，默认就是可疑的。
0.2 版注解 — 美德 vs 仪式的区分。 实证证据揭示并非所有流程摩擦都具有相同性质。摩擦是具备美德的，当它将可被第三方核验的公共信号外化时：在执行中正式命名涌现的风险，使异质的外部审计员能够捕获它们；工作收尾时的 drift-check 在实证验证中以零误报检测出已声明 vs 实际修改的文件错配；用两个异质模型进行的双重审计能进行跨模型校准，并捕获单个审计员会遗漏的缺口。摩擦是可被攻击的仪式，当它仅产生人工分诊或开出处方而不允许根据上下文调整时：与目标模块惯例相冲突的死板模板，或对已在别处记录的偏差仍发出警报的 drift-check，是观察到的两种情形。前者保留；后者是格式的 bug，而非原则的美德。详细证据与可执行的判断标准见 straymark-thesis-validation.md §5（保存在 docs/decisions/proposals/ 中）。
7. Local-first，Cloud 作为放大器
CLI 在本地仓库中可以完全离线工作。这是初次体验，也是其上构建一切的基础。Cloud 的存在是为了放大价值（跨仓聚合、签名证据、语义化历史检索、团队协作），但绝不替代 CLI，也绝不让其变成瘦客户端。
从未连接 Cloud 的用户也必须能够获得产品的大部分价值。这一安排保护工具不受 Cloud 故障模式的影响、不受商业模式变更的影响，也不受"始于本地、终于强制联网"这一产品经典漂移的影响。
8. 项目记忆存活于仓库中，而非外部数据库
AILOG、ADR、AIDEC、Charter 与 Bundle 作为版本化文件与代码并存。原因是结构性的：项目记忆必须能在产生它的产品之外继续存在。如果 StrayMark 明天消失，.straymark/ 目录中的文件仍可读、可解析、可使用——因为它们是结构化的 markdown 与符合公开 schema 的 JSON。
这一决定放弃了集中式后端会更容易实现的若干能力（例如无需同步的瞬时全文检索），但换来了长期可靠性以及用户对自身数据的控制。这种不对称是经过深思的，且是永久的。
9. 简洁优先于能力
当两种设计满足同一目标时，更简单的胜出。当一项功能确有用处但需要显著的复杂度时，最好等到该使用模式至少在三个真实项目中得到验证之后，再将其结晶到产品中。
这同时适用于产品本身与产品的语言。命令名、文档类型、framework 概念都为新用户能够立即理解而选择，不为听起来技术上精巧而选择。如果一个概念对新用户需要冗长解释，多半是设计得不好。
0.2 版注解 — 当 bash 已够用时优先 bash 而非 framework。 实证证据表明，一段约 145 行的 bash 脚本（awk + grep + git）能以零误报覆盖"已声明文件 vs 实际修改文件的偏差"这一情形（基于两次测试）。在 CLI 的语言（Rust）中不优先实现该脚本的有意识决定，理由如下：bash 零构建、无额外依赖、可就地检查；维护成本低。当其在路线图（straymark-cli-roadmap.md，保存在 docs/decisions/proposals/ 中）的第二阶段移植到 CLI 时，应尽可能保留 bash 的简洁——从 Rust 调用 shell，或在重新实现时小心不要让逻辑膨胀。复杂度只在使用模式确实要求时才结晶，而不是默认就结晶。
10. 对工具不做之事保持诚实
StrayMark 不评估模型。不是 LLM 网关。不替代工程师的判断。不防止所有幻觉。不自动颁发法规合规认证。产品页面、文档与公开沟通对此明示无误。
理由是务实的：以现实期望采用工具的用户会留下来。误以为它能做它做不到的事而采用的用户会沮丧地离开。早早对边界保持诚实，是比宽泛承诺更好的市场投资。
11. 社区维护工具，而非反过来
StrayMark 的用户多为对自身用例了解超过产品团队的工程师。贡献、issue 与反馈以专业的尊重对待，路线图决策吸纳这些视角。但这不是民主决策（产品需要一致的愿景），而是作为认真严肃的输入。
这不意味着照单全收社区所求。意味着解释何时说"不"以及为何说"不"，让对话保持公开可见，并接受这一事实：认真使用者带来的智性压力，会让产品比团队孤立的决策变得更好。
12. 产品的速度等于学习的速度
StrayMark 的推进不应快于我们对其实际使用方式的学习。在三个不同项目中获得真实使用数据之前就过早结晶功能，会在那些可能错误的功能上产生高维护成本。等待证据的耐心是纪律，而非懈怠。
具体表现为对以下事项的明确偏好：原型先于功能、观察先于结晶、稳定的 schema 优先于变动的功能、增量演化优先于大规模重写。
0.2 版注解 — 在初期证据有限时仍坚持 N≥3 的精神。 撰写本版本时所掌握的实证证据仅来自一个采用方项目，在一个领域（Go 后端），由单一作者完成。若按字面应用本原则，将阻止任何由该证据出发的结晶。若按其精神应用——结晶之前先严谨观察、以真实数据驱动增量演化——则可用证据涵盖三个结构性多样化的轴向：(a) 工作单元规模的变化（五个周期中包含 XS、S、M），(b) 在实证压力下的格式迭代（v1 → v2 → v3，每一版都源于上一周期），(c) 跨模型审计员校准（两个异质模型在最受压周期中收敛到相近评分）。这六个周期 × 三种格式 × 三种规模，相当于该原则希望保护的 N≥3 等价证据。
仍未多样化的，是领域。为以可执行形式保留该原则：任何由该证据所结晶出的 schema，都以 v0.json 发布并标注实验性。向稳定 v1.0 的过渡，需要在另一领域（前端、ML 流水线、infra-as-code）的第二个项目中完成验证。任何依赖于尚无证据支持之假设的功能——例如条件审批的假设需要多角色流程，而可用证据未演练此情形——在出现确实演练它的项目之前，都被显式地阻塞。论证展开与各假设的具体缺口列表，见 straymark-thesis-validation.md §6 与 §8（保存在 docs/decisions/proposals/ 中）。
检测到的元-元模式 — 格式的自我演化。 实证证据揭示该格式会自我改进：每个执行的 Charter（在历史术语中是 Plan）都会产生数据，进而精炼下一个格式。这暗示在未来版本中扩展该原则：工具与自己一同演化；每一次使用都是下一版本的输入。目前先作为一项观察记录在案，不作为附加原则；待第二个项目确认该模式后再做调整。
如何使用本文档
当出现非平凡的设计决策时，值得明确地将其与十二条原则对照，并记录结果。三种有用的模式：
满足全部原则的决策：照常进行。
与某条原则发生冲突的决策：明确记录正在放宽哪条原则、为何放宽，以及什么样的证据会导致回退该决策。该记录应保存在 AIDEC 或 ADR 中。
违反根本性原则（1、2、3、4）的决策：在没有先审视该原则是否仍然正确之前，不予作出。如果原则仍然正确，决策被舍弃。如果原则已不正确，则在作出决策之前更新原则，而不是之后。
原则每六个月以累积的证据作正式评审。两次正式评审之间的变更也是可能的，但必须是审慎的、经过文档记录的。
本文档是护栏，不是手册。其有效性以"它让我们在多少次决策面前停下来思考"来衡量——那些我们后来本会后悔的决策。