docs: add minimal requirement shaping guidance
This commit is contained in:
@@ -190,7 +190,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文
|
|||||||
|
|
||||||
- `docs/reference/arch.md`:UniDesk 分布式工作平台的长期架构约束。
|
- `docs/reference/arch.md`:UniDesk 分布式工作平台的长期架构约束。
|
||||||
- `docs/reference/repo-tree.md`:仓库结构目标与组件边界。
|
- `docs/reference/repo-tree.md`:仓库结构目标与组件边界。
|
||||||
- `docs/reference/strategy-governance.md`:UniDesk 外部收益约束、短长期收益划分和需求审视准则;战略分析记录见 GitHub issue #7。
|
- `docs/reference/strategy-governance.md`:UniDesk 外部收益约束、短长期收益划分、需求压缩和 reference/plan 拆分准则;战略分析记录见 GitHub issue #7。
|
||||||
- `docs/reference/staff-reference.md`:幕僚长期参考、决策过程和用户偏好摘要;与 `strategy-governance`、`code-queue-supervision` 配套。
|
- `docs/reference/staff-reference.md`:幕僚长期参考、决策过程和用户偏好摘要;与 `strategy-governance`、`code-queue-supervision` 配套。
|
||||||
- `docs/reference/secretary-reference.md`:秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。
|
- `docs/reference/secretary-reference.md`:秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。
|
||||||
- `docs/reference/code-queue-supervision.md`:Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。
|
- `docs/reference/code-queue-supervision.md`:Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。
|
||||||
|
|||||||
@@ -39,6 +39,61 @@ Before accepting a requirement, answer these questions:
|
|||||||
|
|
||||||
If the answers are weak, the requirement should be dropped, narrowed, or rewritten.
|
If the answers are weak, the requirement should be dropped, narrowed, or rewritten.
|
||||||
|
|
||||||
|
## Minimal Requirement Shaping
|
||||||
|
|
||||||
|
Before writing a long-term reference, implementation plan, issue, prompt, or task
|
||||||
|
breakdown for a broad requirement, first compress the requirement to the smallest
|
||||||
|
domain model that satisfies the current external need.
|
||||||
|
|
||||||
|
Use an explicit simplification pass:
|
||||||
|
|
||||||
|
1. List the rich or default architecture that first comes to mind.
|
||||||
|
2. Remove roles, groups, projects, capabilities, services, middleware, gates, and
|
||||||
|
audit surfaces that are not needed for the first useful workflow.
|
||||||
|
3. Produce a before/after table showing what was removed or merged.
|
||||||
|
4. Ask whether the remaining model can be implemented with an existing service,
|
||||||
|
database, and control path before introducing a new microservice or middleware.
|
||||||
|
5. Record postponed components as trigger-based follow-ups, not as phase-one
|
||||||
|
dependencies.
|
||||||
|
|
||||||
|
For example, a multi-user hardware-lab requirement should first check whether
|
||||||
|
`admin/user`, session ownership, and a single grant table are enough before
|
||||||
|
adding group/project RBAC, capability matrices, OpenFGA, Keycloak, service mesh,
|
||||||
|
or Kubernetes tenant abstractions. A middleware is justified only when a concrete
|
||||||
|
trigger appears, such as external identity integration, inherited permissions,
|
||||||
|
tenant self-service namespaces, or admission-policy enforcement that cannot be
|
||||||
|
handled by the existing service boundary.
|
||||||
|
|
||||||
|
## Reference And Plan Split
|
||||||
|
|
||||||
|
When the simplified requirement needs documentation, split the output:
|
||||||
|
|
||||||
|
- `docs/reference/*.md` owns stable design goals, authority boundaries, table or
|
||||||
|
API contracts, request paths, service ownership, and acceptance criteria.
|
||||||
|
- `docs/plan/*.md`, GitHub issues, or project-specific planning docs own current
|
||||||
|
state, source observations, implementation order, migration steps, incompatible
|
||||||
|
changes, and open work.
|
||||||
|
|
||||||
|
The reference must not become a process log. It should explain the target shape
|
||||||
|
as if a future implementer has not seen the chat. The plan should explain how the
|
||||||
|
current source differs from that target and what must change.
|
||||||
|
|
||||||
|
For product or platform designs that touch multiple services, the plan should
|
||||||
|
name each affected service and classify the change:
|
||||||
|
|
||||||
|
- data/schema change;
|
||||||
|
- API or request-chain change;
|
||||||
|
- frontend behavior change;
|
||||||
|
- worker/runtime behavior change;
|
||||||
|
- deployment or namespace/data-plane change;
|
||||||
|
- incompatible behavior that deliberately removes an old route, default, or
|
||||||
|
fallback.
|
||||||
|
|
||||||
|
Do not preserve legacy compatibility just because it existed before. If the user
|
||||||
|
has accepted a simplified target, old assertions, public routes, feature flags,
|
||||||
|
fallbacks, or dual paths that conflict with the target should be removed in the
|
||||||
|
same plan, with the user-facing breakage and migration handling stated clearly.
|
||||||
|
|
||||||
## Short-Term Work
|
## Short-Term Work
|
||||||
|
|
||||||
Short-term work is the work that improves the current usable system quickly.
|
Short-term work is the work that improves the current usable system quickly.
|
||||||
|
|||||||
Reference in New Issue
Block a user