docs: add minimal requirement shaping guidance

This commit is contained in:
Codex
2026-05-28 08:42:35 +00:00
parent 5ecff66f83
commit dc227f3e7d
2 changed files with 56 additions and 1 deletions
+1 -1
View File
@@ -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 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。
+55
View File
@@ -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.