Introduction

In agent development and project collaboration, teams often repeatedly debate decisions that have already been closed, usually because no one remembers why the decision was originally made. The decision-records plugin is designed to solve this problem by helping teams record decisions that are difficult to roll back or difficult to re-debate.

What Is This

decision-records is a lightweight decision-record tool maintained by ChenneyZhuang. It follows the MIT license, with its core value being the recording of the rationale behind a decision, rather than merely recording the conclusion. It requires no template rituals or approval workflows, and it maintains zero dependencies.

Core Features

  • Append-only mode: Add new records that supersede old ones, rather than rewriting history. Rewriting history is what causes records to rot.
  • Zero dependencies: It consists of only one SKILL.md file.
  • Zero ceremony: There are no template rituals or approval workflows.
  • Location: Decision records are stored with the project itself (repository or documentation).

Installation

Run the following command in your terminal:

git clone https://github.com/ChenneyZhuang/decision-records ~/.claude/skills/decision-records

Typical Usage

  1. Create a file named decisions.md in your project documentation, or add it as a section in an existing document, placed next to the work it governs.
  2. Use the standard 5-line format to record decisions.

Example format:

### 2026-09-14 — Use plan B for syncing
- Decision: sync via UUID, not timestamps
- Alternatives: timestamps (rejected: clock skew across devices)
- Why: IDs survive offline edits; timestamps silently drop concurrent rows
- Reversible? yes — migration script exists

Use Cases and Notes

  • Who it applies to: The value is greatest in team collaboration scenarios; individual projects usually only need 2-3 records.
  • When to record: The rationale must be recorded at the moment the decision is made. A record added afterward only repairs memory, not rationale.
  • Context changes: What is recorded is the rationale that existed when the decision was made. Changes in context can turn a decision that was “correct at the time” into one that is now “questionable”; the supersede process is designed for exactly this purpose.
  • Permission check: The plugin runs with the permissions of the current DSH process. Please review the source code and license before installing.

Conclusion

By recording the rationale behind decisions and keeping history readable, decision-records helps avoid repeated debates. For more information, visit the GitHub repository or the DSH directory.