Feature request: Add a standardized code audit module for modular codebases

Open 💬 2 comments Opened Jun 3, 2026 by Heyu2002

What variant of Codex are you using?

App,CLI

What feature would you like to see?

I have an idea for improving how Codex reads and generates code.

When Codex generates code or reads an existing codebase, it would be useful if it could also generate and maintain a standardized “code audit module” for each relevant module or subsystem. This audit module would summarize the structure, responsibilities, interfaces, dependencies, invariants, and important implementation details of the code.

The goal is that, the next time Codex needs to understand the project, it would not always need to reread a large amount of source code from scratch. Instead, it could first read the audit module to quickly understand the design and implementation of that part of the system.

This would be especially helpful for modular code design. Whenever Codex modifies existing code or generates new code, it should also update and maintain the corresponding audit module so that it stays accurate.

I think this could be a practical way for AI agents to fully understand modular codebases, because this is similar to how humans understand and work with code: we build a mental model of each module, its responsibilities, and how it interacts with the rest of the system. A standardized, maintained audit module could make that mental model explicit and reusable.

Additional information

This is just an idea. I understand that something similar could probably be implemented through skills, but I would prefer to see it explored as a standardized convention or built-in workflow. I see this as an experiment in making large modular codebases easier for AI agents to understand, maintain, and evolve over time.

View original on GitHub ↗

2 Comments

Heyu2002 · 2 months ago

I did a small implementation spike for this idea in my fork to validate whether a minimal built-in workflow is feasible.

Proposed MVP:

Add an under-development code_audit feature flag, disabled by default.
Discover .codex/audits/index.md from the workspace.
Inject the audit index as bounded developer context only when the feature is enabled.
Expose a deferred code_audit.read tool for reading specific audit module files.
Require the prompt to treat audit modules as navigation hints, not source-of-truth, and verify source files directly before editing.

Why this shape:

It avoids unbounded context injection.
It keeps the feature opt-in.
It does not require changing core agent behavior broadly.
It works as a small extension-layer MVP rather than a large memory-system change.

Validation in my fork:

Unit tests for prompt construction, path validation, and tool behavior.
Registry-level integration coverage for prompt/tool registration.
App-server v2 integration test verifying the audit index reaches the model request while the read tool remains deferred.
Local formatting, clippy, and targeted package tests pass.

Would the Codex team be open to reviewing a focused PR for this MVP, or would you prefer this to remain an external/plugin-level experiment for now?

Heyu2002 · 2 months ago

I did a focused implementation spike in my fork and added baseline comparison coverage to validate the main goal of this proposal.

The comparison test runs the same workspace twice:

baseline Codex with code_audit = false
Codex with code_audit = true

The baseline request does not receive any audit architecture signal. With code_audit enabled, the model request receives only the bounded audit index, including module paths and short architecture summaries, while large audit module bodies are not included in the initial request. The added request-body size is bounded and much smaller than the full module body.

This validates the intended MVP behavior:

ordinary Codex behavior is unchanged by default
enabling the feature gives the agent a compact project-architecture navigation signal
detailed module summaries remain deferred and are read only when needed
large architecture documents are not blindly injected into model context

Tests added:

prompt-level test that large module bodies are not inlined
app-server integration test that the initial model request contains the index but not large module bodies
baseline-vs-enabled app-server integration test showing the bounded architecture signal added by the feature

Would the Codex team be open to an invited PR for this MVP, or should this remain an external/plugin-level experiment for now?