TARE-Learn/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract.md

Project Knowledge Builder Output Contract

Use this reference when producing a full codebase knowledge base.

Language Policy

Match the user's language for human-facing narrative docs. If the user writes in Chinese or asks for Chinese, write README, context, architecture, runtime, backend, frontend, data, auth/permissions, extension, troubleshooting, RAG guidance and ADRs in Chinese.

Keep technical anchors unchanged: source paths, commands, class names, method names, API paths, config keys, table names, permission codes, JSON keys and metadata enum values.

Generated indexes may remain technical and source-like. Do not hand-translate generated values if it reduces refreshability.

Document Roles

File	Purpose
README.md	Entry point, reading order, high-value links, freshness note. For Chinese output, title and usage guidance should be Chinese.
CONTEXT.md	Domain language, business capabilities, user roles, core nouns, invariants.
CONTEXT-MAP.md	Bounded contexts, module ownership, upstream/downstream dependencies, runtime boundaries.
01-architecture.md	System shape, module graph, request/data/control flows, extension seams.
02-runtime.md	Local run, build, env vars, Docker, deployment modes, process topology. Must identify local, Docker standalone and cloud modes when present.
03-backend.md	Backend modules, entrypoints, API conventions, service/mapper/entity patterns.
04-frontend.md	Frontend bootstrap, routing, state, API client, component/page conventions.
05-data-and-migrations.md	Databases, migrations, schema sources, seed data, table families.
06-auth-permissions.md	Authentication, authorization, token/session flow, permission-code lifecycle. Must explain menu/button permission flow when the repo has backend-driven menus.
07-extension-guide.md	How to add a feature end-to-end, with source-grounded examples. Must cover backend CRUD, frontend page and permission/menu data changes when applicable.
08-troubleshooting.md	Symptom-driven runbook with commands, files, and likely causes.
09-rag-indexing.md	Chunking, metadata, exclusions, refresh cadence, stale-data policy.
adr/*.md	Architecture decisions observed in the current code.
generated/*.md	Data-derived indexes that can be regenerated.

Required Sections

Each narrative doc should include:

• Observed Sources: concrete files or commands used.
• Core Facts: concise source-backed statements.
• Operational Implications: what developers must do differently because of those facts.
• Unknowns/Risks: gaps that need runtime access, DB export, product owner input, or external docs.

For Chinese output, use equivalent section labels:

• 已观察来源
• 核心事实
• 操作影响
• 未知与风险

Newcomer Usefulness Gate

Before considering the knowledge base useful for handoff, verify that a new maintainer can answer:

1. What is the product/project, and which directories matter first?
2. How do I start or identify the active runtime mode?
3. Where are backend endpoints, frontend routes/pages, config, tables and permission codes indexed?
4. How do menu, button and backend permission checks connect?
5. When adding a normal feature, which backend, frontend, database and permission artifacts usually change?

If the answer is not obvious from README plus the narrative docs, add or revise human-facing guidance before finishing. Do not solve this by making generated indexes longer.

Generated Indexes

project-inventory.md

Include:

• repository roots
• build/package manifests
• primary languages
• major directories
• scripts
• Docker/compose files
• env files
• test files

backend-endpoints.md

Include route method, path, class/file, approximate line, auth annotations, and notes. Do not invent full route paths when class-level and method-level mappings require Java expression resolution; show observed fragments and mark composition limitations.

frontend-routes.md

Include static router files, dynamic route loaders, src/views index, route guard files, and external route package loaders.

config-reference.md

Include env files, YAML/properties files, relevant keys, default values, and risk notes. Redact secrets.

database-dictionary.md

Include SQL files, migration files, table names, table families, and whether the table is initialized, migrated, or inferred. Avoid loading huge SQL into prose; summarize and link.

permission-codes.md

Include backend annotations, frontend permission helpers/usages, menu/permission SQL occurrences, and auth lifecycle notes.

ADR Template

# ADR NNNN: Title

Date: YYYY-MM-DD
Status: Observed

## Context

Source-backed facts that show the decision exists.

## Decision

The architecture decision embodied by the current code.

## Consequences

Benefits, tradeoffs, operational constraints, and migration risks.

## Sources

- `path/to/file`

RAG Metadata

Recommended metadata per chunk:

{
  "project": "name",
  "snapshot_date": "YYYY-MM-DD",
  "source_path": "path",
  "doc_type": "architecture|runtime|generated|adr|runbook",
  "domain": "backend|frontend|data|auth|deploy",
  "freshness": "manual|generated",
  "confidence": "observed|inferred|unknown"
}

Anti-Patterns

• A long essay without generated indexes.
• “Best practice” advice unrelated to the repo.
• Copying README marketing text as architecture documentation.
• Claiming an endpoint, table, permission, or runtime mode exists without a source path.
• Hiding unknowns instead of listing them.