Back to Details

gjalla-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Goal

目标

The best, most elegant and effective software systems are ones that are well-informed, well-planned, and verifiable. The final output is a plan/spec that can act as a reference doc, covering the problem/motivation, technical approach, deltas (what properties of the system will change once implemented), and verification criteria. The first step is always understanding the current state. Use gjalla (CLI or MCP) to fetch the relevant parts of the master spec, including the architecture, capabilities, data flows, etc that are relevant to this problem/solution space. Also fetch the gjalla rules so you know what boundaries there are on your final solution. Once you undersatnd the relevant properties and constraints, identify any specific details that you need from the source code and gather them. Now you have everything you can find yourself. Are there any outstanding questions that will affect the specifics of the solution you propose? If so, ask the user for input.
When you have everything you need, go ahead and use 
gjalla spec new
which will scaffold a change spec for you to edit. This is necessary for workflows where specs are artifacts are canonical, and the gjalla platform will facilitate verifying and merging changes into the master spec once implementation is complete. The user may prefer that you present the plan as a Claude Plan or a Cursor Plan (or another alternative based on your identity as an agent)... that's fine. Once the plan is approved for implementation, write the approved information into a gjalla spec and continue on.
The information needed for a production-grade spec / reference doc includes the following:
  • Problem Statement: What user or system problem does this solve?
  • Goals: What must be true when this is done?
  • Non-Goals: What is explicitly out of scope?
  • Behavioral Requirements: Observable behaviors the feature must exhibit, in other words, new capability properties that will be present within the system.
  • Technical Approach: How will this be built? How will this affect architecture, data flows, surace area, and other gjalla primitives?
  • Verification Strategy: Unit, integration, and acceptance test plan.
  • Dependencies: What must exist or be deployed first?
  • Rollback Plan: How to safely revert if something goes wrong.
最优质、最优雅且最高效的软件系统都是信息充分、规划完善且可验证的。 最终产出是一份可作为参考文档的计划/规范，涵盖问题/动机、技术方案、变更点（功能实现后系统哪些属性会发生变化）以及验证标准。 第一步始终是了解当前状态。使用gjalla（CLI或MCP）获取主规范的相关部分，包括与该问题/解决方案领域相关的架构、能力、数据流等。同时获取gjalla规则，以便了解最终解决方案的边界。 在理解相关属性和约束后，确定需要从源代码中获取的具体细节并收集它们。 现在你已经掌握了所有能自行找到的信息。是否存在会影响你提出的解决方案细节的未解决问题？如果有，请向用户寻求输入。
当你掌握所有所需信息后，使用
gjalla spec new
命令，它会为你生成一个变更规范的模板供你编辑。对于规范作为标准化工件的工作流而言，这是必要的，gjalla平台将在实现完成后协助验证并将变更合并到主规范中。 用户可能更希望你以Claude Plan或Cursor Plan（或基于你的Agent身份的其他替代格式）呈现计划……这没问题。一旦计划获批可实施，将获批信息写入gjalla规范并继续推进。
生产级规范/参考文档所需的信息包括以下内容：
  • 问题陈述：此功能解决了用户或系统的什么问题？
  • 目标：完成后必须达成哪些要求？
  • 非目标：明确哪些内容不在范围内？
  • 行为要求：功能必须具备的可观察行为，即系统中将新增的能力属性。
  • 技术方案：该功能将如何构建？会对架构、数据流、交互面以及其他gjalla原语产生哪些影响？
  • 验证策略：单元测试、集成测试和验收测试计划。
  • 依赖项：必须先存在或部署哪些内容？
  • 回滚计划：如果出现问题，如何安全回滚。

Guidelines

指南

  • Specs and plans are not novels. Background information and context is totally acceptable (in fact its preferred) as long as the information is clear, salient, and not overly verbose.
  • The goal is to get ahead of unintended consequences (use second order thinking) and to make sure there are no surprises for the humans
  • 规范和计划不是长篇小说。背景信息和上下文完全可以包含（实际上更推荐），只要信息清晰、突出且不过于冗长。
  • 目标是提前规避意外后果（运用二阶思维），确保不会给相关人员带来意外。