write-notes-like-deepseek

Write Notes Like DeepSeek

The method is distilled from the engineering practice of DeepSeek Harness . The Agent in the chat handles breaking down tasks and planning schedules; this Skill does only one thing: why it was changed this way, what was given up, and how it was proven correct all stay in one place, for the next person who modifies this code.

Red line: first decide whether to write, then discuss how to write

Models have an OCD for appeasement and want to create a Note at every turn. Pass this gate first:

Quick return — the following fall under DSH's definition of "purely mechanical or local changes"; creating a Note is strictly forbidden, change the code directly:

Pure formatting, typos, unambiguous renaming
Style adjustments (without changing behavior)
Dependency patches (without changing behavior), version release tagging (RC/Release tag)
Routine CRUD, explicit logic fixes within a single module that are understood by reading the diff (no cross-file impact)

Judgment aligned with DSH: non-trivial changes must be written up. Hitting any of the following makes it non-trivial — changedbehavior, changedarchitecture, changedcross-file contracts, changedprocesses and toolchains, changedtesting strategy, changedpersistence / network / configuration formats— or other decisions that maintainers may revisit later.

Before writing, think clearly against three directions about what this note guards:

Looking forward (establishing new rules)— newly created cross-module communication contracts, state transition rules, access boundaries, runtime invariants. If not recorded, later Agents each write their own set and arbitrarily breach modules.
Looking back (recording compromises)— giving up mainstream or intuitive solutions for invisible constraints. If not recorded, rejected old paths will be walked again.
Doing subtraction (narrowing)— destructive refactoring, code trimming, narrowing the API exposure surface. If not recorded, no one knows the exit conditions and migration boundaries, and the subtraction cannot proceed — or it goes too far.

Remember in one sentence:Intentions, boundaries, and trade-offs that code and unit tests cannot express are non-trivial. When judgment is uncertain, err on the strict side.

For AI, rules written in prose are as good as no rules — disciplines that can be mechanically checked all have scripts as a fallback (see §6); decision reversals, on-the-spot audits, and present-tense body text rely on operational flow, not lexical scanning. Priority: the host project's AGENTS.md / CLAUDE.md and the user's direct instructionstake precedence over this Skill; this Skill is a default contract, not a higher law.

Inner excuse	Reality
"It's just changing a default value/renaming"	Default values and naming are both decision facts; updating an old note in place takes only 30 seconds
"Merge first, fill it in later"	Later = never; decay starts with every "fill it in later"
"Code is documentation"	Code only sayswhat, it cannot saywhyandwhat was given up
"The change is small, no need"	Small scale ≠ no need to record; a single retry parameter once caused a network-wide outage
"Not sure whether to write it"	Compare against the non-trivial list above: if it matches, write it; if it doesn't, don't write it. Don't use this sentence as a shield.

Prefer in-place synchronization; don't create new unless necessary: In DeepSeek's public evolution history, the bulk of Note changes is in-place modification of existing Note facts (paths, class names, default parameters), not creating new files. Directly update the existing entry for changes that already have an owner!
Don't rewrite one Note into another decision: Facts (paths, symbols, defaults) are changed in place; if a decision or rationale is reversed → create a new entry and cross-link. Don't rewrite ## Decision into its opposite, and don't rely solely on git as the only copy of the old rationale.
Audit on the spot when writing a new entry; don't postpone: Search proposed + implemented + rejected by module name/keyword; classify each match on the spot: irrelevant / partially overlapping (cross-link) / fully absorbed (delete or archive) / outdated proposal (reject or delete). The classification result lands on disk together with this new Note.
Garbage doesn't go into the archive: Outdated proposals are converted to Status: rejected — <原因>(archiving is strictly forbidden); rejected records with no pitfall-prevention value are physically deleted directly.

A "decision" isn't heavy — in a personal project it's just "why A was chosen over B". Choices, trade-offs, and pitfalls you've stepped in are all worth writing down.

0. Probe first, then land

Don't set up the full directory set right away. Choose according to what this repository currently looks like:

If there is AGENTS.md / CLAUDE.md / contributing guide → read it; if there is docs/adr/、docs/decisions/, Issue templates, or other ready-made decision records → follow them, with status and kind per this Skill's folders.
No ready-made decision records → build per the standard structure:.agents/notes/{proposed,implemented,rejected,archived} × 6 class, create whichever directory is needed, no need to pre-create empty directories — write it personally, and even without git still build the full structure, don't trim it down to a single directory.
Long-term team repository → layer the process on top of the same structure:CONTRIBUTING.md / add a line to the PR template: "important changes must come with a note", and wire the validation script into CI.

1. Path is classification

Each Note's path is its identity:{lifecycle}/{class}/yyyy-mm-dd-topic.md

Lifecycle (one folder level, how far this entry has progressed):

proposed — idea stage, a plan exists but hasn't landed yet
implemented — already landed, kept in sync with the same batch of code changes
rejected — proposals carefully rejected, kept only when they can prevent repeat mistakes, otherwise delete the whole group
archived — implemented records that are complete and of low future reference value, frozen and unchangeable

Class (second-level folder, just these 6; adding more requires changing the check script):

feature New capability — choices visible to users or the model (non-obvious behavior also counts)
bug-fix Bug fix — what was fixed, or filling a gap exposed in a retrospective
simplification Delete only, add nothing — no new capability, only removing code, behavior, or surface
architecture How the structure is built — how the shipped source code is organized, how packages connect
process Tools and process — checks, releases, how to collaborate (around code, not runtime behavior)
testing How to write tests — test strategy and infrastructure

refactor Not listed separately: if visible behavior changed, classify under the corresponding class; if it didn't change, it's simplification. Don't create INDEX.md. For detailed criteria see references/classification.md。

2. File format (the check script will verify)

The first three lines are fixed:

# Agent Note: <标题>

Status: <状态>

The status must be consistent with the lifecycle folder it's in (rejected with a one-sentence reason); the filename date is thefirst proposed date. Body skeleton:

proposed：## Problem → ## Proposal → …free section… → ## Alternatives considered → ## Acceptance criteria → ## Risks
implemented：## Problem → ## Decision(present tense) → …free section… → ## Alternatives considered → ## Consequences
rejected: the frozen proposal form, with the conclusion on the Status: line

Alternatives are mandatory: record only opponent options genuinely considered, and write its strongest reason first before refuting it. Do not fabricate options that never existed. Write “do nothing / reuse the status quo” only if it was truly weighed at the time. The script only checks whether there is ## Alternatives considered。 implemented of ## Decision in present tense; the gate only rejects proposal titles (## Proposal / ## Plan / ## Migration plan / ## Acceptance criteria and its Chinese aliases). For details see references/note-format.md。

For the template see templates/。

3. Search historical decisions before acting (4 decentralized methods)

Before refactoring or choosing technologies, first check historical constraints to prevent repeating pitfalls or breaking prior compromises:

Entry comments (if any): If the code entry already has // Note: ... 见 .agents/notes/..., follow it. If not, use the three methods below; do not add anchors just to search.
Physical slicing by category tree: Do not scan the whole repository; cut directly into directories by intent (for architecture see implemented/architecture/, for pitfalls see rejected/）。
Precise global search: Use ripgrep to search keywords or mechanism names,always include --hidden and exclude archived/：
```
rg --hidden --glob '!.agents/notes/archived/**' "<机制名或关键词>" .agents/notes/
```
Drill down through module documentation: When a submodule README involves design rationale, follow the relative Markdown link directly to the corresponding Note.

Before asking the user, check it yourself. Do not throw facts that the above four methods can answer to the user; only real decisions should take up the user's time.

4. When to write, when to modify

Trigger signals in conversation—when the user or yourself says something like this, it is time to write (except for mechanical changes in the red-line list at the top of the document; do not use these phrases as a reason for over-recording):

Settling on a new route: “just choose X”, “decided to use X”, “we'll use X for now” → triggers a Note
While comparing: “how to choose between X and Y”, “why lean toward X” → triggers alternatives recording
The same reason has been explained a second time → it should be written down

Determination and operation flow:

Refactoring an existing architecture / path migration / parameter change → [Preferred: sync in place]: Directly correct the facts in the old Note holding that decision (code paths, method signatures, default values), do not start a new note, and do not append a running history to the body.## Decision The core reason remains unchanged; if the reason changes, create a new note.
Before writing a new Note → search active notes by module name/keyword and classify on the spot (see “on-the-spot audit” at the top of the document); do not leave it for a future big cleanup.
New idea, not yet acted on → first write proposed(why you want to do this, which paths were considered); act after review. See below for interaction discipline.
After construction (proposed → implemented), complete in the same change: ① move to implemented/<class>/, leave the filename date unchanged; ② Status: proposed → Status: implemented；③ ## Proposal → present tense ## Decision；④ ## Acceptance criteria / ## Risks fold into ## Consequences(or present tense ## Testing); ⑤ delete the plan section. Land it in the same batch as the code——in a git scenario, the same commit/PR。
The solution is partially superseded by a new decision → Keep both, add reciprocal links on each side; only update facts that still hold. Archiving is prohibited.
The approach is fully superseded by a new decision → The new Note takes over and records all unique rationale/alternatives/consequences/verification gaps from the old one; after inbound links are updated, delete if possible, and if not possible (the old one still has independent leverage), then archive-agent-note.ts. The pointer goes in the new note, not in the archived one.
Skip-writing scenarios: see the red line at the top of the document—if it is in the quick-return list, commit the code directly.

Interaction protocol (when asking the user questions):

Separate facts and decisions first: look up facts available in the environment yourself (code, note tree, rg) before asking; only trade-offs that truly need a decision should take up the user's time.
Throw everything in one round: list all questions awaiting decision by number, each on its own line with a recommended answer ➡️ <推荐>; the user responds in batches by number ("1 yes, 2 the second option"), without squeezing out answers or probing back and forth.
Convergence relies on a confirmation gate, not on a cap on the number of questions: before writing/acting, restate all decisions, and execute only after the user confirms consensus—any point silently dropped in the restatement is corrected by the user at confirmation; do not act without confirmation.
More than five open decisions is a signal, not a quota: it means the change is too large—split it into multiple notes, or first submit a proposed draft for review; do not cram it into a single conversation.

For detailed criteria see references/when-to-write.md, for archiving and deletion see references/archiving.md。

5. How to write it well

## Consequences Write at the same timecosts and benefits, not just "what was given up".
Free sections (package topology, wire contracts, schema, etc.) go between Decision and Alternatives , keeping searchable mechanism names and the emphasis on must / may / never timing.
Use relative Markdown links for cross-Note references [topic](../../implemented/architecture/2026-…-….md), not bare numbers, so they are mechanically verifiable.
If the host already has this convention, a line may be left at the core entry point // Note: ... 见 .agents/notes/...; it is not a gate. When a decision is superseded, these comments are the code checklist to be synchronized.
For writing style and removing derivation traces see references/prose-checklist.md; for simplification opportunities see references/simplification-checklist.md。
After writing, go through the semantic self-check in references/quality-gate.md and report to the user onlygaps and what was written well(≤5 lines), with concrete fixes for gaps. Structure relies on scripts, meaning relies on human approval.

6. Validation and operations commands

Run directly at the repository root (when npm scripts are configured):

npm run verify-agent-note-tree     # 目录合法性、分类、文件名、笔记间相对链接
npm run verify-agent-note-format   # 头块、状态、必备节、备选方案、implemented 禁用提案标题
npm run verify-archived            # 归档封印：头部布局、manifest 哈希、只增不改（无 git 自动降级）
npm run verify-notes               # 以上三线串跑（CI 用这个）
npm run archive-agent-note -- <path> [--superseded-by <新笔记>]  # 一键归档；可选在新笔记插入互链 + 入站死链报告
npm run check-anchors              # 软报告：若代码里有 // Note: 锚点，做双向体检；不当 CI 门
npm run init-board                 # 生成 ~69KB 轻量看板 board.html（日常开发推荐）
npm run bundle-board               # 打包内嵌全量数据的自包含 demo.html

The script is located in this Skill's scripts/, invoked fromthe host project root, and by default checks .agents/notes/under the current directory. First determine the Skill location based on the loaded SKILL.md path; do not assume that scripts/exists at the host root, and do not switch to the Skill directory to execute. Installation does not automatically configure the host's npm scripts.

When installed at the project level into .agents/skills/ , you can run directly:

npx tsx .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts
npx tsx .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts
npx tsx .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts
npx tsx .agents/skills/write-notes-like-deepseek/scripts/build-board.ts --init board.html "项目决策看板"

When installed into .claude/skills/ or a global directory, replace the above prefix with the actual Skill path. The kanban packaging parameter is --bundle <notes目录> <输出.html> "名字"; for parameters and immunity rules see references/verification.md。

Teams can copy this Skill's templates/verify-notes.yml to the host repository .github/workflows/verify-notes.yml, adjust it to the actual installation path, and commit the project-level Skill files together; templates inside the Skill directory will not be executed. You can add it in CONTRIBUTING.md / PR template, add a line: "Important changes must come with a note.".

References

Load on demand:

references/note-format.md — header block and body skeleton expansion
references/classification.md — 6-class determination and boundaries
references/when-to-write.md — when to create / update / transition (including an explanation of the alignment relationship with DSH determination)
references/archiving.md — archiving and merge deletion (including the "future reference value" determination)
references/prose-checklist.md — writing style and de-leakage self-check
references/simplification-checklist.md — simplification opportunity self-check
references/quality-gate.md — post-writing semantic self-check: Problem / Alternatives / Consequences / Verification determination + reporting form
references/verification.md — validation script description