write-notes-like-deepseek: decision notes your coding agent cannot ignore

The failure mode this project is aimed at

The README opens with a claim about AI-heavy repositories: each new session starts from a blank slate and sees only the code in front of it. A deliberately awkward function that avoids a deadlock looks like an obvious cleanup target. A cross-layer call that bypasses an old protocol looks like progress. A design that was tried three months ago and rejected for memory reasons gets proposed again, because nobody wrote down that the road was already walked.

The project's framing of the root cause is the part worth quoting: code expresses how the system runs now, not why it has to run that way or what was given up. That is a documentation argument, and it is not new. What is new is the audience. The README states that the DeepSeek Harness team verified in their own repository that coding agents follow enforced gates far more reliably than prose conventions, and that since the labor is already done by AI, the usual excuse that gates are too much trouble does not hold.

So the target user is a team or individual whose pull requests are mostly authored by agents, working in a repository where architectural decisions get made inside those same sessions and then evaporate. If your changes are styling, formatting, version bumps, or behavior-preserving dependency patches, the README explicitly says to skip the notes and just commit.

How the note tree works: directory as state

There is no index file. The README argues that a global INDEX.md is the hottest conflict source when several branches are open at once, since every note edit touches it. Instead, the path carries the state: proposed/, implemented/, rejected/, archived/, each under a six-way category split.

The path format is strict: {stage}/{category}/yyyy-mm-dd-topic.md. The six categories are feature, bug-fix, simplification, architecture, process and testing. Inventing a seventh is not a style question; the tree verification script rejects it. The simplification category has a definition worth noting: deletions only, no additions, which is where behavior-preserving refactors go.

The lifecycle has three steps. Before work starts, a draft goes into proposed/ and every rejected option must first be stated in its strongest form, then dismissed. After landing, the note moves to implemented/ and is written in the present tense only. When a decision is superseded, the old note is physically moved into archived/, gains a single Archived: line, and the new note carries the cross-links.

The sealing is mechanical rather than voluntary. Each archived note gets a SHA-256 seal recorded in manifest.json, and that file is append-only, so a single edited character in the archive trips verification. The archive script also prints every reference still pointing at the old note, and the README's rule is that no dangling link survives the night. Archived notes drop out of daily verification but are never deleted, so a future session proposing the old approach runs into the archive snapshot and the new note's links.

Installing the Skill and writing the first note

The README gives one install command, run from the repository you want to maintain. It uses the skills CLI and points at the GitHub path.

npx skills add czm15053/write-notes-like-deepseek

After that, the note directory itself has to exist. The README's structure block shows the four stage folders under .agents/notes/, and the tree verification script is what enforces the layout, so creating the folders by hand and then verifying is the honest sequence.

mkdir -p .agents/notes/proposed/architecture
npx tsx scripts/verify-agent-note-tree.ts

A first note in proposed/ needs a problem statement, the alternatives with their strongest case, and acceptance criteria. The README's own excerpt from DeepSeek Harness shows the implemented shape: Problem, Decision, Alternatives considered, Consequences, with Status: implemented at the top. The format script enforces the skeleton, requires the alternatives section, and rejects proposal-style headings in implemented notes. It does not scan body wording.

The verification commands are also exposed as package.json scripts, so a team can wire them into CI with one line.

{
  "scripts": {
    "verify-notes": "npx tsx scripts/verify-agent-note-tree.ts && npx tsx scripts/verify-agent-note-format.ts && npx tsx scripts/verify-archived-agent-notes.ts"
  }
}

Archiving is a script call rather than a manual move. The README shows the invocation with a --superseded-by flag that writes the back-link into the new note, not into the archived one.

npx tsx scripts/archive-agent-note.ts .agents/notes/implemented/<类别>/<文件名>.md \
  --superseded-by .agents/notes/implemented/<类别>/<新笔记>.md

What the scripts actually check, and where they stop

The README describes three verification scripts plus one optional checker. The tree script covers directories, categories, filenames and relative links between notes. The format script covers the status line, required sections, the mandatory alternatives section, and the ban on proposal headings inside implemented notes. The archive script checks the header layout of archived notes, the seal hash, and append-only behavior, degrading gracefully when git is unavailable. The optional anchor checker looks for // Note: comments in source that point at notes which no longer exist, and it only warns.

The honest limitation is scope. These are structural checks. Nothing in the described set verifies that the alternatives section is truthful, that the consequences section admits a real cost, or that the decision was correct. A note can pass every script while being a well-formatted rationalization. The README's own advice that a decision without costs is a curated one is a norm, not a gate, and norms are exactly what the project argues agents ignore. That tension is not resolved by the tooling as described.

The second limitation is adoption surface. The tree script rejects unknown categories, which means a repository with an existing docs/decisions/ folder of ADRs cannot simply point this at it. The notes live at .agents/notes/ with a fixed shape, and the README states the structure is identical for individuals and teams. There is no documented import path for an existing decision log, so a migration means rewriting notes into the prescribed skeleton or running two systems side by side.

The alternatives: ADRs, and why the gate is the difference

The obvious comparison is the architecture decision record, the long-standing pattern of a numbered markdown file in a docs folder with Context, Decision and Consequences. The overlap is large. Both capture the why. Both expect the record to be committed alongside the change.

The difference is enforcement. A conventional ADR folder has no script that exits non-zero when a heading is wrong, no seal that detects an edited archive, and no link check that fails when a superseded record is still referenced. The README's stated position is that the entire value comes from this enforcement gap, citing the DeepSeek Harness observation that agents follow enforced gates far better than prose conventions. Whether that observation generalizes beyond one repository is not something the README attempts to show; the demo board with 974 notes is evidence of volume, not of the claim.

The second alternative is doing nothing and relying on prompt instructions such as "respect the architecture." The README dismisses this directly, and the dismissal is the project's whole thesis. If you accept that thesis, the ADR comparison collapses into a question of whether you want to write the extra scripts yourself. If you do not accept it, this project is a more opinionated ADR folder with a Node dependency.

Maintenance cost, licence and the parts the README leaves open

The last push to the repository was on 2026-09-14, three days before this writing, and the repository is not archived. That is the only maintenance signal available; there are no retrieved releases, and version 0.1.0 in package.json with private set to true suggests the tooling is pre-1.0 and not published as a library.

The licence situation needs care. The README carries an MIT badge and links a LICENSE file, but the repository metadata does not report a licence. A badge is not the same as a detected licence file, and anyone adopting this inside a company should read the LICENSE file in the repository root rather than the badge. Nothing here is legal advice, and the discrepancy is worth resolving before the scripts are copied into a commercial repository, which the README explicitly permits by saying the scripts/ directory can be copied into any project.

Upgrade cost is low in one direction and unclear in another. The scripts depend only on Node.js 18 or later and run through npx tsx, so there is no build step and no runtime dependency to track. The unclear part is the note format itself. The format script enforces a skeleton, and the tree script enforces a fixed category list. Any future change to that skeleton is a migration of every existing note, and the README does not document a migration path or a format version. The archived notes are the harder case: they are append-only by design, so a format change that touches the header layout would either break the seal check or require the seal manifest to be regenerated, which is exactly the operation the seal exists to prevent.

Editorial conclusion

Adopt it if AI agents open most of your pull requests and nobody remembers why a module boundary exists. Skip it if your changes are routine CRUD or you work alone without git and never revisit a decision. Before committing, run npx tsx scripts/verify-agent-note-tree.ts and npx tsx scripts/verify-agent-note-format.ts against a single real note and confirm the exit codes behave as the README describes; the format script is the one that rejects proposal-style headings in implemented notes.

Frequently asked questions

Official sources

1. czm15053/write-notes-like-deepseek on GitHub
2. Issues
3. README