gjalla-spec

目标

优秀、优雅且有效的软件系统，往往具备充分的信息、周密的规划，并且可验证。 最终产出是一份计划／规范，可作为参考文档，涵盖问题／动机、技术方案、变更（实现后系统哪些属性会发生变化）以及验证标准。 第一步始终是了解当前状态。使用 gjalla（CLI 或 MCP）获取主规范中的相关部分，包括与此问题／解决方案相关的架构、能力、数据流等内容。还要获取 gjalla 规则，以了解最终方案有哪些边界。 了解相关属性和约束后，找出需要从源代码中确认的具体细节，并收集这些信息。 现在，你已经掌握了所有能自行找到的信息。是否还有会影响拟议方案具体内容的待解决问题？如果有，请向用户征求意见。

收集到所需信息后，使用 gjalla spec new 为变更规范搭建框架，再进行编辑。对于规范工件具有权威性的工作流，这一步必不可少；gjalla 平台会在实现完成后协助验证变更并将其合并到主规范中。 结合最终目标、上下文（架构、数据流、用例等）以及规则／约束，认真思考并设计出优雅、易维护且有效的解决方案。

生产级规范／参考文档应包含以下信息：

• 问题陈述：这要解决什么用户或系统问题？
• 目标：完成后必须满足什么条件？
• 非目标：哪些内容明确不在范围内？
• 行为需求：该功能必须展现哪些可观察行为，换言之，系统中将具备哪些新的能力属性。对于系统允许或禁止某项行为的需求，应将其表述为系统状态，而非用户所见，并注明负责执行该约束的文件和函数。没有代码位置负责实现的需求，只是一厢情愿。
• 威胁模型和安全要求：此设计考虑了哪些对抗性安全情形？安全软件系统需要具备哪些属性，并通过相应测试确保不会出现回归？
• 技术方案：如何构建？这会如何影响架构、数据流、接口范围以及其他 gjalla 原语？
• 验证策略：正向、负向和边界情况的单元测试与集成测试是基本要求；还应考虑安全与防护（即测试是否涵盖常见的安全编码陷阱，例如 AI OWASP Top 10，或可能使系统易受攻击的其他安全错误）、可维护性、性能、用户体验，或合规、业务约束、平台约束等特定领域的验证标准。至少列出一项目前会失败、而构建完成后会通过的测试；如果列不出，说明目标还不够具体，无法据此实现。
• 依赖项：必须先具备或部署哪些内容？如果项目属于某个系统，请查阅 gjalla，确认这是否会影响互操作性。
• 回滚计划：出现问题时如何安全回退？

指南

• 规范和计划不是小说。完全可以提供背景信息和上下文（事实上也很推荐），但内容必须清晰、切题、相关且不过于冗长。
• 目标是预先发现意外后果。请进行二阶思考，提前识别潜在意外。

展示并绑定

当你对写入规范的解决方案感到满意后，应将其展示给人类审批——这是 gjalla-autonomous 流程中的两个人工审核关卡之一（另一个在提交时）。如果你有原生的计划展示机制（Claude 计划模式、Cursor 计划），请使用该机制；否则，请直接展示规范并等待。未经明确批准，不要开始实施。

获得批准后，开始实施。如果你使用 Claude Code，gjalla 会自动记录该批准；无需进行其他标记。