docs: add minimal requirement shaping guidance
This commit is contained in:
@@ -190,7 +190,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文
|
||||
|
||||
- `docs/reference/arch.md`:UniDesk 分布式工作平台的长期架构约束。
|
||||
- `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/secretary-reference.md`:秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。
|
||||
- `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.
|
||||
|
||||
## 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 is the work that improves the current usable system quickly.
|
||||
|
||||
Reference in New Issue
Block a user