2026-08-31 21:05:24 +08:00

2.1 KiB

Enterprise Knowledge Platform — Codex Rules

Read first

Before modifying code, read the documents relevant to the task:

  • docs/product/PRD.md
  • docs/architecture/ARCHITECTURE.md
  • docs/architecture/ADR.md
  • docs/api/API_CONTRACT.md
  • docs/api/MCP_CONTRACT.md
  • docs/plans/V1_EXECUTION_PLAN.md
  • docs/plans/TASKS.md
  • docs/development/DEFINITION_OF_DONE.md

Do not redesign accepted architecture unless the task explicitly asks for an architecture change.

Architecture invariants

  1. API First.
  2. V1 uses a modular monolith plus independent async/GPU workers and an MCP gateway.
  3. PostgreSQL + object storage hold canonical data.
  4. Vector databases are rebuildable indexes, not sources of truth.
  5. Business services depend on VectorStore abstractions, never directly on Mochow.
  6. Embedding, reranking, parsing, OCR, object storage, and LLMs use provider interfaces.
  7. Original source documents are immutable.
  8. Compiled Knowledge is derived and traceable to source document versions/chunks.
  9. ACL is resolved before or during retrieval. Never retrieve global Top-K and filter afterward.
  10. MCP exposes business capabilities, not infrastructure/provider details.
  11. Index profiles are versioned; model/chunk changes use shadow indexes before activation.
  12. Do not split V1 into unnecessary microservices.
  13. Never hardcode credentials or production endpoints.
  14. Core retrieval changes require tests and RAG regression evaluation.

Task discipline

  • Work on one Task ID at a time.
  • Keep scope limited to the task.
  • Do not opportunistically implement future tasks.
  • Update relevant contracts/docs when behavior changes.
  • Add useful code comments/docstrings and record file or behavior changes in the relevant docs/progress log.
  • After validation, push and merge the task branch into main before starting the next Task ID.

Before finishing

Run relevant checks: format, lint, typecheck, unit tests, relevant integration tests, migration checks, API/MCP contract checks, and RAG evaluation for retrieval changes.

Report changed files, tests/results, unresolved risks, and follow-up tasks.