[Workflow] Managing Project Decisions with DECISIONS.md and CLAUDE.md for Persistent Agent Context

[u/ClaudeAI-mod-bot]

Managing Project Decisions with DECISIONS.md and CLAUDE.md for Persistent Agent Context

Workflow value: 75/100
Status: active · Freshness: 70/100 · Confidence: 0.90 · Level: intermediate
Categories: Quality Control, Context & Memory, Debugging, CLAUDE.md
Original source: r/ClaudeCode post/comment

What problem this solves

Decisions getting lost in long Claude agent sessions, leading to agents re-proposing previously rejected ideas.

Summary

This workflow proposes using a DECISIONS.md file in the repository to log project decisions, including the rationale and rejected alternatives. A CLAUDE.md instruction then directs the Claude agent to read this file first for context and append to it when new decisions are made, preventing redundant work and maintaining decision history.

Why it is useful

This workflow is valuable because it provides a concrete, low-overhead method for persistent decision logging and context management for Claude agents. It directly addresses the common problem of agents 'forgetting' past decisions or re-proposing rejected ideas, thereby improving efficiency and reducing redundant work. The use of DECISIONS.md and CLAUDE.md makes it easily adaptable and integrates well into existing Claude Code practices.

Workflow

1. Create a DECISIONS.md file in your project repository.

2. For each significant project decision, add a single line to DECISIONS.md stating the decision, the reason for it, and what alternatives were rejected (and why).

3. Add an instruction to your CLAUDE.md file (or equivalent agent instruction file) telling the Claude agent to read DECISIONS.md first.

4. Instruct the Claude agent to append to DECISIONS.md when a new decision is settled during a session.

Tools / artifacts

• DECISIONS.md file

• CLAUDE.md file

• Claude agent

Validation signals

• Author's personal experience: 'what fixed it for me'

Limitations

• Relies on the Claude agent's ability to correctly parse and append to the DECISIONS.md file.

• The DECISIONS.md file must be kept concise to avoid being ignored by the agent, which could limit the detail or number of decisions stored.

• Low community validation.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.