what is the best way to modify an AGENTS.md file to change scope of project, but not lose the work already accomplished?

Software Development

Changing Project Scope with Codex

To modify a project's scope without losing work, it's essential to take a snapshot of the current state, archive completed deliverables, and update the AGENTS.md file to reflect the new direction. This process clears the agent's context window of outdated goals while preserving a trail of its previous accomplishments.

Step-by-Step Modification Strategy

  1. Take a Repository Snapshot: Commit all current work to save the current stable state in your version control history.
  2. Archive Completed Work: Move previously achieved milestones to a project management tracker or a dedicated completed.md file, so the agent knows what foundational work is in place.
  3. Update the AGENTS.md Sections:
    • Scope & Objectives: Rewrite the Project Scope section to detail the new goals, non-goals, and the final state of the project.
    • Progressive Disclosure: Break down large, specialized guidelines into targeted modular files (e.g., docs/style_guide.md, docs/database_schema.md) and reference them in your root AGENTS.md.
    • Files in Scope: Clearly define the directory boundaries of the newly scoped work.
  4. Tell the Agent Its New Focus: Start a fresh chat or session and instruct your agent to read the updated AGENTS.md and newly added documentation to align with the new goals.

Letting Codex Self-Author AGENTS.md

Codex can edit its own AGENTS.md file, which is one of the most efficient ways to update project rules, system behaviors, or custom command documentation. However, managing its read/write timing and session lifecycle is crucial to prevent confusion.

Back to all articles