Overview
The deliverable of this stage is not "translating code into documentation", but establishing theauthoritative entry:
components/{module}.md: module boundaries and collaboration entrycontracts/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)
- Code entry:
- External interfaces and contract entry:
- API:
../contracts/api/{module}.md - Data:
../contracts/data/{module}.md
- API:
- 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)
- Key test entry:
contracts/api/{module}.md
- Authoritative entry (must be locatable):
- OpenAPI/Proto file:
<path 或外部链接> - Gateway/routing entry:
<path>
- OpenAPI/Proto file:
- 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/命令或配置路径>
- handler/routing:
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)
- Schema/DDL/migration:
- 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/命令或配置路径>
- Key read/write paths:
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-dictionaryand 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)