SuperAPI AI Directory

aisdlc-project-discover-modules-contracts

Coding & development

View repository

Updated 10-16 09:56

About this skill

aisdlc-project-discover-modules-contracts (Step4: Module pages + contract entry pages)

Overview

The deliverable of this stage is not "translating code into documentation", but establishing theauthoritative entry:

  • components/{module}.md: module boundaries and collaboration entry
  • contracts/api|data/{module}.md: contract authoritative entry + invariant summary + evidence entry

At the start, announce:"I am using the aisdlc-project-discover-modules-contracts skill to generate component pages and API/Data contract entry pages for the module, and to establish the evidence chain."

Output files

  • .aisdlc/project/components/{module}.md
  • .aisdlc/project/contracts/api/{module}.md
  • .aisdlc/project/contracts/data/{module}.md
  • Backfill:
    • .aisdlc/project/components/index.md
    • .aisdlc/project/contracts/api/index.md
    • .aisdlc/project/contracts/data/index.md

Minimal template (copyable)

components/{module}.md

  • Module positioning: In/Out (explicitly state what it is not responsible for)
  • Owner: team/person in charge (can link to contact list/on-call)
  • Entry:
    • Code entry:<目录/路由/handler/consumer/job/cli 的路径>
    • Runtime entry:../ops/<...>(if any)
  • External interfaces and contract entry:
    • API:../contracts/api/{module}.md
    • Data:../contracts/data/{module}.md
  • Representative collaboration scenarios (1-2): write only "who calls whom + key boundaries", not detailed sequences
  • NFR allocation summary: performance/availability/security key points (write only guardrails and entries)
  • Evidence links:
    • Key test entry:<tests/...> or CI job
    • Key monitoring/alerting entry:<dashboard/alert>(if any)

contracts/api/{module}.md

  • Authoritative entry (must be locatable):
    • OpenAPI/Proto file:<path 或外部链接>
    • Gateway/routing entry:<path>
  • Invariant summary (3-7 items, write "commitment boundaries"):
    • Authentication/authorization model (who can call)
    • Idempotency/retry semantics (how clients can safely retry)
    • Error code families/error classification (stable contract)
    • Versioning/compatibility strategy (change window)
    • Audit/compliance requirements (if any)
  • Evidence entry:
    • handler/routing:<path>
    • Tests:<path>
    • CI gate:<job/命令或配置路径>

contracts/data/{module}.md

  • Data ownership (Ownership): primary write/read-only/sync source (explicit boundaries)
  • Core objects and primary keys: object name + primary key/unique identifier + one-sentence lifecycle
  • Authoritative entry:
    • Schema/DDL/migration:<path>
    • ORM model:<path>(if applicable)
  • Invariant summary (3-7 items):
    • Key definitions (e.g., status meanings, amount/time definitions)
    • State machine/lifecycle constraints
    • Uniqueness/foreign keys/immutable fields (write only stable constraints)
  • Evidence entry:
    • Key read/write paths:<repo path>
    • Key tests:<tests path>
    • CI gate:<job/命令或配置路径>

Quality gates (P0 must satisfy)

  • The three files of a P0 module must all exist and cross-link correctly
  • Both contract pages must have the "three-piece set": authoritative entry + invariant summary + evidence entry
  • Anything "uncertain" must not be written as a full field catalog or speculative conclusion; it can only:
    • Write the entry placeholder for "not found/to be located"
    • Write how to find the evidence next (specific to file type/directory clues)

Common mistakes

  • Turning the contract page into a field dictionary: The contract page of Discover is a summary of entry points and invariants, not a full field specification.
  • Writing only paths, not invariants: This makes it impossible to understand the "stable commitment boundary" during collaboration.
  • No evidence entry point: Subsequent verification becomes impossible, and the implementation and tests cannot be located.

Red-flag checklist (if any one appears: stop and correct)

  • Adding .aisdlc/project/docs/api-reference、data-dictionary and other directories to pile up field-level details
  • Pasting a large number of field tables into the contract page without links to authoritative entry files
  • Writing collaboration scenarios as a detailed sequence (this should be left to requirement-level/change-level artifacts, not project-level ones)