smart
143 lines
5.5 KiB
Markdown
143 lines
5.5 KiB
Markdown
# 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
|
|
|
|
```markdown
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|