tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/.specify/memory/constitution.md
tangweijie aba7071723 docs: 建立项目宪法并同步 speckit 模板 
将项目约束正式落到 .specify/memory/constitution.md，并同步更新 plan、spec、tasks、checklist、agent 模板，使 Speckit 工作流默认遵循文档单一真源、范围收敛、Archive 隔离与校验闭环。
2026-03-13 10:45:13 +08:00

7.5 KiB
Raw Blame History

福建水务营收系统 Constitution

Core Principles

I. 主文档单一真源

正式内容 MUST 优先落在既有主文档中维护：docs/design/01_Overview/03_Summary_Design.md、docs/design/02_Detailed_Design/01_Detailed_Design.md、docs/design/03_Technical_Design/01_Database_Design.md、docs/design/03_Technical_Design/03_Interface_Design.md、docs/design/03_Technical_Design/04_Security_Design.md、docs/design/03_Technical_Design/05_Deployment_Design.md。若既有主文档可以承载内容，任何规格、计划、任务或实施说明 MUST 引导回主文档修订，不得默认创建“新版本”“最终版”“修订版”等平行正式稿。

Rationale：本仓库的首要目标是形成可评审、可交付、可持续维护的正式文档体系；平行稿会直接破坏单一真源。

II. 范围交集优先

新增或补完的功能、模块、接口、外部系统与约束 MUST 先落在当前范围基线内。范围判断 MUST 以 docs/design/01_Overview/03_Summary_Design.md 与 docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md 的交集收敛：两者均覆盖可直接推进；仅一方覆盖 MUST 标记“需确认”；两者均未覆盖 MUST 视为超范围并停止扩写。

Rationale：当前项目以“对齐既有设计、保守补完”为主，不以新需求发散为目标。

III. Archive 隔离与可追溯

docs/design/04_Appendix/Archive/ MUST 作为来源、核对与归档区使用，默认不作为正式主稿直接改写替代。引用 Archive 内容时 MUST 回写到 P0/P1 正式文档后再作为正式结论输出。迁移归档资料时，Markdown 文件与同名 _images/ 目录 MUST 成组维护，引用路径 MUST 同步修复，来源关系 MUST 可追溯。

Rationale：Archive 的价值在于追溯与核对，而不是替代正式交付口径。

IV. 一致性优先于扩写

所有修改 MUST 优先保证系统名称、数据库口径、模块编号、接口编号、图表、链接和术语的一致性。正式系统名称 MUST 使用“福建水务营收系统”；接口编号 MUST 与模块编号区分并优先采用 IF- 前缀；图表 MUST 优先使用 Mermaid 并与正文一致；仓库内引用 MUST 使用相对路径。无依据时 MUST 先修正结构和一致性，不得为了“完整”而臆造实现细节、代码、DDL 或伪代码。

Rationale：对当前仓库而言，不一致比不完整更容易导致评审和实施偏差。

V. 校验与台账闭环

每次正式文档变更后 MUST 执行与改动范围匹配的最小校验，并在适用时回写管理台账。单文件修订至少 MUST 执行 make validate-file FILE=<目标文件>；涉及链接、目录或跨文档引用时 MUST 执行 make check-links；涉及图表时 MUST 执行 make validate-mermaid；重要治理或结构变更 MUST 更新 docs/design/00_Management/01_Project_Progress.md，明确任务完成时 SHOULD 同步更新 docs/design/00_Management/03_Task_Checklist.md。

Rationale：本仓库的交付价值依赖“文档可读 + 链接有效 + 图文一致 + 台账可追踪”的闭环，而不是仅完成局部文字编辑。

文档与资料约束

  • 正式文档内容 MUST 使用中文；技术术语、框架名、代码标识符可保留原文。
  • 文档层级 MUST 与抽象粒度匹配：概要设计讲边界与结构，详细设计讲流程/规则/接口/数据，技术专项讲数据库/接口/安全/部署等专题。
  • Speckit 产物若用于本仓库，MUST 默认把“文档修订”视为交付对象，而非默认生成软件代码结构。
  • 需求、计划、任务、检查清单 MUST 明确来源文档、影响文档、验收方式与是否涉及台账更新。
  • 未经用户明确要求，规格与计划 MUST 避免把实现代码、数据库脚本、部署脚本、压测指标或测试细节写成默认必交付项。

执行流程与质量门禁

  1. 开始任何正式文档任务前，执行者 MUST 先阅读：
    • docs/design/00_Management/01_Project_Progress.md
    • docs/design/00_Management/02_Delivery_Standards.md
    • docs/design/00_Management/03_Task_Checklist.md
    • 与任务直接相关的目标文档
  2. 结构性调整任务还 MUST 额外阅读：
    • docs/design/00_Management/04_Writing_Guide.md
    • docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md
    • docs/design/00_Management/10_AI_Retrieval_Whitelist.md
    • docs/design/00_Management/11_Main_Doc_Chapter_Index.md
  3. 计划文档 MUST 在“Constitution Check”中显式检查：主文档归属、范围基线、Archive 使用方式、一致性影响、校验与台账动作。
  4. 任务文档 MUST 将“目标文档修订”“链接/图表校验”“台账同步”列为显式任务，而不是隐含工作。
  5. 质量门禁最低要求 MUST 满足：断链数量为 0、Mermaid 语法错误为 0、平行正式稿新增数量为 0、关键口径冲突数量为 0。

Governance

本 Constitution 高于 .specify/ 下其他模板中的默认假设；若模板、计划或任务与本 Constitution 冲突，MUST 以本 Constitution 为准并同步修订模板。

修订流程如下：

  1. 先基于当前主文档、治理文档与必要的 Archive 来源形成修订草案。
  2. 在修订草案中明确版本变更类型，并说明是 MAJOR、MINOR 还是 PATCH 及其依据。
  3. 同步检查 .specify/templates/、README.md、AGENTS.md 及相关运行指导文档是否仍与宪法一致；若不一致，MUST 在同一轮修订中更新或显式记录 pending 项。
  4. 所有规格、计划、任务与检查清单在生成或更新时 MUST 执行一次合规复核，确认满足五项核心原则。

版本策略如下：

  • MAJOR：移除核心原则、重定义治理边界、改变单一真源或范围控制方式。
  • MINOR：新增原则、增加新的强制门禁或新增治理章节。
  • PATCH：纯措辞澄清、错别字修正、非语义调整。

合规复核要求如下：

  • 每份计划 MUST 记录 Constitution Check。
  • 每份任务清单 MUST 能映射到目标文档、校验动作与台账动作。
  • 每次重要变更完成后 MUST 在结果摘要中说明修改文件、校验结果、剩余风险与后续建议。

Version: 1.0.0 | Ratified: 2026-03-13 | Last Amended: 2026-03-13