SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsproject-discover-modules-contracts

project-discover-modules-contracts

General & other

View repository

Updated 10-16 01:28

About this skill

project-discover-modules-contracts (Step 4: module single-page SSOT + contract section + evidence chain)

Overview

The module page is Discover's "authoritative entry point." Its goal is not to write out every detail, but to let AI/humans, when needed, quickly determine boundaries and invariants, and follow the evidence chain to locate code/contracts/tests/CI/ops。

At the start, announce:"I am using the project-discover-modules-contracts skill to build a single-page SSOT for the module (including the contract section and evidence chain)."

Hard rules (P0 must satisfy)

  1. The module page path is fixed
    • .aisdlc/project/components/{module}.md
  2. Anchor headings must exist (stable navigation)
    • ## TL;DR
    • ## API Contract
    • ## Data Contract
    • ## Evidence（证据入口）
    • ## Evidence Gaps（缺口清单）
  3. Do not create a separate directory for contracts
    • Prohibit .aisdlc/project/contracts/**
  4. Gaps must be structured
    • All gaps should be written only to ## Evidence Gaps（缺口清单）(scattered "to be added/not found/TODO" is not allowed)
  5. Do not use "placeholder sentences" to masquerade as content
    • In API Contract / Data Contract / Evidence and other body text, it is forbidden to write placeholder sentences such as "to be filled in after completion/to be confirmed/not found/to be added later."
    • If evidence or conclusions are missing: only write to ## Evidence Gaps（缺口清单）, and keep body paragraphs short and traceable.

Module page Frontmatter (required)

---
module: <module-short-name>
priority: P0|P1|P2
change_frequency: high|medium|low
last_verified_at: <YYYY-MM-DD>
source_files:
  - <path/to/key/file1>
  - <path/to/key/file2>
---

Tip：change_frequency can use the empirical judgment of git log or simple statistics;source_files only select the key source files that best represent the module boundary/contract/state machine.

Recommended module page structure (minimum viable)

# <模块中文名>（<module>）

## TL;DR
<3–5 句话：做什么、边界、关键不变量、最关键的证据入口>

## 模块定位
- In：
- Out：

## Owner
- 团队/负责人/值班入口：

## 入口
- 代码入口：
- 运行入口（如有）：../ops/...

## 协作场景（1–2 个）
- 谁调用谁 + 关键边界（细节时序下沉到 spec）

## State Machines & Domain Events
- 状态机摘要：
- 领域事件摘要：

## API Contract
- 权威入口（必须可定位）：
- 不变量摘要（3–7 条）：
- 证据入口（最小粒度）：

## Data Contract
- 数据主责（Ownership）：
- 核心对象与主键：
- 权威入口（必须可定位）：
- 不变量摘要（3–7 条）：
- 证据入口（最小粒度）：

## Evidence（证据入口）
- Code：
- Tests：
- CI：
- Ops：

## Evidence Gaps（缺口清单）
- 缺口：
  - 期望补齐到的粒度：
  - 候选证据位置：
  - 影响：

How to write the contract section (avoid a "full list of fields")

## API Contract Minimum requirements (P0)

  • Authoritative entry point (must be clickable/locatable)
    • Source file path or generated artifact path for OpenAPI/Proto/Schema
    • If there is a generation/validation command or CI job, write the entry point (do not write long explanations)
  • Invariant summary (3–7 items)
    • For example: authentication method, idempotency semantics, versioning strategy, error code family, audit requirements, timeout/retry strategy
  • Evidence entry points (minimum granularity)
    • At least N key handler/router/controller file paths
    • At least 1 representative test entry point (if none, go to Evidence Gaps)
    • At least 1 CI job/command entry point (able to prove "whether tests were run/whether contract validation was done")

## Data Contract Minimum requirements (P0)

  • Data Ownership
    • Primary write/read-only/sync source (clear boundaries)
  • Core objects and primary keys
    • Object name + primary key/unique identifier + one-sentence lifecycle
  • Authoritative entry point (must be locatable)
    • Evidence entry points for migrations/DDL/Schema/ORM model
  • Invariant summary (3–7 items)
    • For example: uniqueness constraints, status definitions, key enums, immutable fields, reconciliation definition entry points
  • Evidence entry points (minimum granularity)
    • Key repository/mapper/service paths
    • Test/CI evidence entry points (if none, go to Evidence Gaps)

Evidence Gaps (gap list) template (mandatory structured)

Any "cannot find/uncertain/to be supplemented" must be written according to this structure, to avoid gaps being scattered and thus never fully filled.

Special reminder: If you are temporarily unable to provide a "3–7 invariant summary", do not write "to be filled in after completion" in the main text. Correct approach: add a gap entry in Evidence Gaps (for example, "Gap: API invariant summary not extracted"), and clearly state the candidate evidence location and impact. At this point, this module must not be checked off in the index.

## Evidence Gaps（缺口清单）

- 缺口：未发现 OpenAPI/Proto 权威入口（无法确认接口字段与错误码族）
  - 期望补齐到的粒度：定位到具体 schema 文件路径或生成 job 名
  - 候选证据位置：`docs/`、`api/`、`openapi/`、CI workflow 中的 build-docs job
  - 影响：需求设计与实现阶段会猜接口契约，容易破坏兼容性与回归成本高

P1/P2 downgrade rules (avoid scope runaway)

  • P1: the module page must exist; API or Data may be missing one of them, but the gap and impact must be clearly written in Evidence Gaps
  • P2: by default, do not create a module page, only reserve a placeholder in the index; upgrade to P1/P0 when needed

Red flag checklist

  • The contract section is written as a full list of fields (should be changed to: authoritative entry + invariant summary + evidence entry)
  • "Gaps" are scattered in the main text as TODO/to be supplemented (must be centralized in Evidence Gaps)
  • Writing placeholder sentences such as "to be filled in after completion/not found/to be supplemented later" in the main text (must be changed to Evidence Gaps)
  • Repeating module page content in the index (the index only navigates)

Common mistakes

  • Writing the "evidence entry" as "what you should do" (write where it is, not how to operate)
  • Writing one-off delivery details into the project-level module page (should be pushed down to spec or an external runbook)