diff --git a/AGENTS.md b/AGENTS.md index b2eba420..39be2c98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。 diff --git a/docs/reference/strategy-governance.md b/docs/reference/strategy-governance.md index 58377ce2..e61f0669 100644 --- a/docs/reference/strategy-governance.md +++ b/docs/reference/strategy-governance.md @@ -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.