CODE.md

The Format

CODE.md is a self-contained, plain-text representation of a codebase’s structure and behavior.

It defines the execution flow, dependencies, API surface, data writes, external integrations, security boundaries, UI interactions, and change history of a project—so that these realities can be followed consistently across coding sessions and between different AI agents and tools.

A CODE.md file contains two parts:

• YAML front matter (machine-readable structural tokens)
• Markdown body (human-readable rationale and guidance)

The YAML front matter contains code tokens: structured facts about the codebase.
The markdown body provides rationale: how to interpret those facts and how agents should use them when generating or editing code.

Getting Started

1. Run CodeVal (or your analysis pipeline) on the repo.
2. Generate a CODE.md file under /codeval/CODE.md.
3. Commit CODE.md to the repository so agents can read it.
4. Keep CODE.md updated as the codebase evolves.

Agents scanning the repo should treat /codeval/CODE.md as the code truth layer for the project.

Code Tokens

CODE.md may embed code tokens in a structured format. These tokens describe:

• Flow (callgraph)
• Dependencies (filegraph)
• Entry points
• Core modules
• Risk hotspots
• Complex areas
• Unused code
• API endpoints
• Data writes
• Third-party calls
• Security checkpoints
• UI behavior
• Change history

Code tokens are embedded as YAML front matter at the beginning of the file.

Example Front Matter

---
version: 1
generated_by: codeval
generated_at: 2026-06-29T01:18:00Z

entry_points:
  - path: src/main.py
    symbol: main

api_endpoints:
  - method: GET
    path: /users
    handler: api/users.getUsers

core_system_files:
  - path: src/lib/database.ts
    dependents: 42

high_risk_areas:
  - path: src/lib/auth.ts
    reason: "Used by many critical flows"

complex_areas:
  - path: src/lib/workflows.ts
    reason: "Calls many other modules"

unused_code:
  - path: src/legacy/old_report.py
    reason: "No callers in callgraph"

data_write_locations:
  - path: src/lib/database.ts
    operations: ["insert", "update"]

third_party_calls:
  - path: src/lib/payments.ts
    services: ["Stripe", "PayPal"]

security_checkpoints:
  - path: src/lib/auth.ts
    checks: ["isAuthenticated", "hasRole"]

ui_behavior_map:
  - component: UserList
    triggers: ["fetchUsers", "deleteUser"]

change_history:
  recently_changed:
    - path: src/lib/database.ts
      last_commit: 2026-06-28
  high_churn:
    - path: src/lib/auth.ts
      commits_last_90_days: 37
  stable_files:
    - path: src/lib/logger.ts
      last_changed: 2024-01-10
---

Code Token Schema

The schema below defines the structure of all CODE.md tokens.

version: 
generated_by: 
generated_at: 

entry_points:
  - path: 
    symbol: 

api_endpoints:
  - method: 
    path: 
    handler: 

core_system_files:
  - path: 
    dependents: 

high_risk_areas:
  - path: 
    reason: 

complex_areas:
  - path: 
    reason: 

unused_code:
  - path: 
    reason: 

data_write_locations:
  - path: 
    operations: 

third_party_calls:
  - path: 
    services: 

security_checkpoints:
  - path: 
    checks: 

ui_behavior_map:
  - component: 
    triggers: 

change_history:
  recently_changed:
    - path: 
      last_commit: 
  high_churn:
    - path: 
      commits_last_90_days: 
  stable_files:
    - path: 
      last_changed: 

The Specification

Agents should treat the front matter as normative: it is the source of truth for how the codebase is structured.

The markdown body that follows should:

• Explain the architecture at a high level
• Call out important patterns and conventions
• Describe how different subsystems interact
• Give guidance on how agents should use the tokens

CODE.md is updated automatically as the codebase evolves. Agents can rely on it to reduce hallucinations and reason accurately across the entire repo.