The developer manual is an executable contract, not launch copy frozen after publication. A code change should answer how developers use it, how failures are diagnosed, how operators verify it, and what evidence supports a delivery promise.

Source-of-truth order

Buildable source and generated output on the current branch;
automated tests, CI workflows, and release scripts;
CONTEXT.md, applicable .ai/constraints, architecture documents, and ADRs;
configuration examples and runtime environments;
roadmap and historical documentation.

When lower-priority material conflicts with source, update it or mark it as history. Do not use an old plan to override current behavior.

Completion standard

update matching Chinese and English paths together;
verify commands, paths, type names, configuration keys, and links against the repository;
distinguish shipped, extensible, designed, and not-shipped capability;
cover important failure surfaces such as denial, retry, tenant isolation, and recovery;
do not turn at-least-once into exactly-once or best effort into an atomic transaction;
link every new page from an index or a related page;
bump frontmatter lastUpdated so Recently updated can list the page;
record capability-level changes in the changelog; do not keep a second handwritten page ledger;
pass npm run build, internal-link, locale-parity, and git diff --check validation.

Recommended sweeps

# ① Run from the repository root; each command is an independently verifiable step.
rg -n "src/BuildingBlocks|SaaS.Contracts|Mapster|AutoMapper|exactly.once" \
  src/content public/diagrams

rg -n "计划中|尚未实现|Planned|not yet implemented" src/content/docs

comm -3 \
  <(find src/content/docs/zh -name '*.mdx' | sed 's#.*/zh/##' | sort) \
  <(find src/content/docs/en -name '*.mdx' | sed 's#.*/en/##' | sort)

A match is not automatically wrong, but each one needs an explanation. Historical release notes may contain an old name; current guides, diagrams, and commands should not teach an old path.

Writing standard

Start with the reader’s problem, then explain the model and procedure. Avoid slogans and stacked adjectives. Use tables for comparison and lists for genuinely parallel information. Keep code short enough to expose the decision, and distinguish real source names from application examples.

Build a page fact card

Before drafting, record audience, task, source owner, declaration, Host composition, configuration, success, failure, degradation, tests, and unimplemented gaps. An interface proves an extension seam only. Usable capability requires implementation, composition, and evidence together.

Topic: finalize a Files upload
Declaration: IFileStore / FinalizeUploadCommand
Composition: concrete File Store in PersistenceRegistration
Success: object exists, hash agrees, file record completes
Failure: missing session / hash conflict / unavailable Store
Gaps: malware scan, session expiry, idempotent repeated finalize
Evidence: handler tests + provider parity + consumer test

The fact card is not a prose template. It prevents an ideal interface from becoming an overstated tutorial and lets reviewers locate evidence for each claim.

Code-example standard

Examples belong to the page’s business scenario. Do not copy one skeleton across modules and merely rename its types. Explain prerequisites, stable identifier source, failure branch, transaction or idempotency boundary, and business meaning after return.

Long blocks carry at least two explanatory comments, but count is not the objective. Good comments explain why a choice is required rather than translating syntax. Identify non-compiling material nearby as pseudocode, configuration, or response example without turning the heading into a disclaimer.

// Reuse the original business-fact identifier; retries must not generate a new key.
var command = new FinalizeUploadCommand(sessionId, expectedSha256);
var result = await mediator.Send(command, cancellationToken);

if (result.IsFailure)
{
    // Preserve stable Error.Code; callers never parse localized error text.
    return result.Error.ToProblem(httpContext);
}

// Success means only the current boundary, not an unimplemented malware scan.
return Results.Ok(result.GetValueOrThrow());

Diagrams and accessibility

Diagrams explain relationships, sequence, state, or ownership across components. Mermaid fits flow, state, and small relationship diagrams; complex architecture uses the shared SVG/HTML generator. Both require zoomable viewing, text alternatives, and prose explanation. Essential rules cannot live only in an image.

Verify type names, arrow direction, and deployment boundaries against source. After architecture changes, run diagram-source verification and visually sample both locales. Valid SVG XML does not prove correct content.

Locale parity is not literal translation

Chinese and English share information architecture, facts, example stages, diagrams, and link targets while using natural language in each locale. Do not translate terms word-for-word or omit a risk boundary from one locale.

Create paired paths first. A rename also updates sidebar, cross-links, source-fact manifests, search vocabulary, and redirects.

Editing workflow

Read repository rules and directly applicable architecture constraints.
Search the target page, peer locale, declaration, composition, and tests.
Build the fact card and classify current, designed, and pending behavior.
Update both locales, diagrams, source map, and links together.
Run content, source, strict depth, module, and diagram gates.
Build and sample desktop and mobile pages.
Record command output, uncovered risk, and rollback in the PR.

Full gate

# Content, locale, source, module, and diagram consistency.
npm run verify:docs
npm run verify:docs-source
npm run verify:docs-depth
npm run verify:modules
npm run verify:module-source
npm run verify:diagrams

# Type checking, static site, search index, and patch formatting.
npm run check
npm run build
git diff --check

Strict depth must reduce baseline pages to zero and cannot be satisfied by generic filler. After build, inspect warnings, indexed page count, and critical interactions. A Mermaid, highlighting, Callout, table, or custom-component change needs a visual sample of an affected page.

Review questions

Can the reader complete a real task and diagnose principal failures?
Does every claim of support, automation, idempotency, atomicity, or production readiness have implementation and test evidence?
Does each example belong to this module, with comments explaining business boundaries?
Do diagrams match current physical architecture and remain readable when zoomed?
Does the page separate current behavior, extension seam, plan, and deployment responsibility?
Do locales agree, and do links and source paths resolve?

When an implementation gap is found, narrow the manual first and record feature work in the matching knowledge-base architecture topic. The manual describes current boundaries honestly; the knowledge base owns future implementation planning.