codex - 💡(How to fix) Fix Feature request: Add a Rule Health Check system for AGENTS.md, project rules, and agent instructions

Summary

I would like Codex to add an optional Rule Health Check / Rule Maintenance Assistant for AGENTS.md, project rules, repository-level instructions, and other long-term agent guidance.

The main idea is that Codex should be able to help users detect when their rules are outdated, redundant, too broad, conflicting, or no longer optimal because the project, platform, SDK, or Codex itself has changed.

Background

For long-running projects, users often maintain many Codex rules, such as:

• AGENTS.md
• Project-specific instructions
• Repository-level agent rules
• Platform-specific development constraints
• Build, test, release, and deployment workflows
• Safety rules
• Long-term preferences for how Codex should work inside a project

These rules may be correct when they are first written, but they can become outdated over time.

For example, I develop iOS and macOS apps. My project rules may contain instructions about Apple platforms, SwiftUI, Xcode, iOS/macOS compatibility, SDK limitations, App Store review requirements, build commands, and testing workflows. However, Apple platforms, SDKs, Xcode, Swift, and App Store policies keep changing. A rule that was useful before may later become unnecessary, too conservative, or even misleading.

The same issue also applies to Codex itself. As the Codex app evolves and gains new capabilities, older AGENTS.md files or agent rules may no longer be the best way to guide the agent. Some old rules may not take advantage of new Codex features, while others may contain limitations that are no longer needed.

Current problem

Right now, users have to manually maintain these rules. This creates several problems:

1. Users may not know which rules are outdated
   A rule may have been written months ago for an old project state, old SDK behavior, old build process, or old Codex limitation. The user may no longer remember why the rule was added.

2. Old rules can continue to affect Codex behavior
   If AGENTS.md contains outdated instructions, Codex may keep following them and produce worse solutions, use outdated workflows, or avoid better modern APIs.

3. Rule files can become bloated
   Over time, users may add many rules to solve specific historical issues. Some of those rules may no longer be useful, but they still consume context and influence agent behavior.

4. Conflicting or vague rules are hard to detect
   A project may have rules that conflict with each other, are too broad, or do not match the current repository structure anymore.

5. There is no proactive warning system
   Users usually only discover rule problems after Codex makes mistakes, fails a task, or behaves in an unexpected way.

Proposed feature

Please consider adding a Rule Health Check feature to Codex.

This could be an optional feature that scans project rules and gives the user a report about possible issues. It should not automatically rewrite rules without user approval. Instead, it should provide reviewable suggestions.

What the Rule Health Check could detect

Codex could inspect AGENTS.md, project rules, and other agent instructions for issues such as:

• Outdated platform assumptions
• Outdated SDK, framework, or API guidance
• Old Codex feature limitations that no longer apply
• Build or test commands that no longer match the current project
• Rules that conflict with current dependency versions or target versions
• Rules that conflict with each other
• Rules that are too broad and should be scoped to a subdirectory
• Rules that are redundant or repeated
• Rules that are vague and likely to cause inconsistent agent behavior
• Rules that are too long and waste context
• Rules that could be moved into a reusable checklist, skill, or more specific instruction file
• Safety rules that are incomplete or no longer match the project structure
• Instructions that may cause Codex to avoid better modern solutions

Possible triggers

The check could run in several ways:

• Manually, through a “Check rule health” button
• After Codex app updates
• After major Codex feature changes
• After dependency, SDK, Xcode, Swift, iOS, macOS, Node, Python, or framework version changes
• After build or test workflow changes
• After repeated agent failures related to the same instruction
• When Codex detects that a rule refers to an old condition that may no longer apply

Suggested product design

Codex could add a section like:

Project Settings → Rules → Rule Health Check

The report could show suggestions like:

Example report item 1

Type: Outdated platform assumption
File: AGENTS.md
Rule: “Avoid API X because it is unstable on iOS 18 beta.”
Reason: This appears to be based on an old beta limitation and may no longer apply.
Suggested action: Add a version condition, update the rule, or remove it if it is no longer relevant.
Risk level: Warning
Confidence: Medium

Example report item 2

Type: Build workflow mismatch
File: AGENTS.md
Rule: “Always run command A before building.”
Reason: The repository appears to now use command B in the current build workflow.
Suggested action: Replace command A with command B, or clarify when command A is still needed.
Risk level: Critical
Confidence: High

Example report item 3

Type: Codex feature upgrade suggestion
File: AGENTS.md
Rule: A long manual checklist for a repeated workflow.
Reason: This may be better represented as a shorter instruction, reusable checklist, skill, or more specific project rule.
Suggested action: Refactor the rule to reduce context usage and make it easier for Codex to follow.
Risk level: Suggestion
Confidence: Medium

Risk levels

It would be helpful if Codex classified suggestions into levels:

• Critical: The rule may cause unsafe actions, incorrect releases, broken builds, or serious project mistakes.
• Warning: The rule may be outdated, conflicting, or causing inefficient behavior.
• Suggestion: The rule still works, but could be clearer, shorter, or better adapted to newer Codex capabilities.
• Info: Codex is only informing the user about a possible improvement or new feature.

User control

This feature should be fully user-controlled.

Recommended behavior:

• Do not automatically change rules without user approval.
• Show a diff before applying any changes.
• Let the user accept or reject each suggestion.
• Let the user mark a rule as intentionally preserved.
• Let the user ignore a suggestion permanently or temporarily.
• Let the user choose whether to check only the current repository or all Codex projects.
• Let the user choose whether Codex can use project code, dependency versions, build logs, test failures, or historical task failures to evaluate rule quality.

Why this matters

For long-term projects, rule files themselves become a form of technical debt.

If rules are outdated, Codex may continue following old assumptions and produce worse results. This can lead to:

• Lower-quality code changes
• Broken build or test workflows
• Failure to use newer platform capabilities
• Overly conservative implementation choices
• Repeated mistakes caused by stale instructions
• Larger and less useful context
• More manual maintenance work for users

A Rule Health Check system would help users keep their Codex configuration accurate, modern, and efficient.

Expected benefit

This would make Codex more reliable for long-running projects. It would also help users maintain high-quality AGENTS.md files and project rules without having to manually audit every instruction over and over again.

Codex already helps users write and maintain code. It would be very useful if Codex could also help maintain the rules that guide Codex itself.