write-notes-like-deepseek

DeepSeek のようにノートを書く

方法は DeepSeek Harness のエンジニアリング実践から抽出しました。チャット内のエージェントがタスクを分解し、計画を立てます。この Skill が行うのはただ一つです。なぜこのように変更したのか、何を断念したのか、どうすれば変更が正しいと証明できるのかを、一か所に残し、次にこのコードを変更する人が使えるようにします。

最優先事項：書くべきかを先に判断し、書き方はそのあと

モデルには迎合する傾向があり、何かとノートを書きたがります。まずはこの関門を通してください。

即時リターン——以下は DSH が定義する「機械的、または局所的な変更」に該当します。ノートを書くことは厳禁とし、そのままコードを変更してください。

• 純粋な書式設定、誤字修正、曖昧さのない名前変更
• スタイル調整（動作を変更しないもの）
• 依存関係のパッチ（動作を変更しないもの）、バージョンリリースのタグ付け（RC/Release tag）
• 通常の CRUD、差分を見るだけで理解できる単一モジュール内の明示的なロジック修正（ファイルをまたぐ影響がないもの）

DSH の基準に合わせて判断してください：非自明な変更には必ず記録が必要です。 次のいずれかに該当すれば非自明です——動作、アーキテクチャ、ファイル間の契約、プロセスとツールチェーン、テスト戦略、永続化／ネットワーク／設定形式を変更する場合、または将来、他のメンテナーが見直す可能性のある決定。

書く前に、次の3つの観点から、このノートで何を守るのかを明確にしてください。

1. 前を見る（新しいルールを確立する）——新たに作るモジュール間通信の契約、状態遷移のルール、アクセス境界、実行時の不変条件です。記録しないと、後続のエージェントがそれぞれ別の実装を行い、モジュールの境界を簡単に破ってしまいます。
2. 後ろを見る（妥協を記録する）——見えない制約のために、業界標準や直感に反する解決策を選んだことです。記録しないと、却下した古いやり方が再び試されます。
3. 削る（範囲を狭める）——破壊的なリファクタリング、コードの削減、API の公開範囲の縮小です。記録しないと、終了条件や移行境界が誰にも分からず、削減を進められなくなるか、やりすぎてしまいます。

一言で覚えてください。コードと単体テストでは伝えられない意図、境界、トレードオフは、すべて非自明です。 判断に迷ったら、厳格に扱ってください。

AI にとって、散文に書かれたルールは、ルールがないのと同じです。機械的に検査できる規律は、すべてスクリプトで担保します（§6 を参照）。決定の反転、その場での監査、現在形の本文は、語彙スキャンではなく運用フローで担保します。 優先順位：ホストプロジェクトの AGENTS.md ／ CLAUDE.md とユーザーの直接の指示は、この Skill より優先されます。この Skill はデフォルトの契約であり、上位の規則ではありません。

心の中の言い訳	現実
「デフォルト値／名前を変えるだけ」	デフォルト値も名前も決定事項です。既存ノートの該当箇所を更新するだけなら30秒です
「先にマージして、あとで補足する」	あとで = 永遠にしないということです。劣化は「あとで補足する」ノートから始まります
「コードがドキュメントだ」	コードが説明するのは何かであり、なぜかや何を断念したかではありません
「変更が小さいから、記録するまでもない」	規模が小さい ≠ 記録しなくてよい、です。あるリトライパラメーターが全ネットワークの障害を引き起こしたこともあります
「書くべきか分からない」	上記の非自明な変更の一覧に照らしてください。該当すれば書き、該当しなければ書きません。この言葉を言い訳にしないでください

• まず既存のノートを更新し、必要がなければ新規作成しない：DeepSeek の公開された進化の歴史では、ノートの変更の大半は既存ノートの事実（パス、クラス名、デフォルトパラメーター）をその場で更新したものです。新しいファイルを作ったわけではありません。既存のノートに該当する変更は、そのノートを直接更新してください。
• ノートの決定を別の決定に書き換えることは禁止：事実（パス、シンボル、デフォルト値）はその場で更新します。決定や理由が覆った場合は、新しいノートを作成して相互リンクします。## Decision を反対の内容に書き換えることは禁止です。以前の理由を残す唯一の手段として git に頼ることも禁止です。
• 新しいノートを作成したら、その場で監査し、先送りしない：モジュール名やキーワードで proposed + implemented + rejected を検索します。ヒットしたノートはそれぞれその場で分類します：無関係／部分的に重複（相互リンク）／完全に取り込み済み（削除またはアーカイブ）／古い提案（却下または削除）。分類結果は、新しいノートと一緒に保存します。
• 不要なものをアーカイブしない：古い提案は Status: rejected — <理由> に変更します（アーカイブは厳禁）。落とし穴を防ぐ価値のない却下記録は、ファイルごと物理的に削除します。

「決定」は大げさなものではありません。個人プロジェクトなら、「なぜ B ではなく A を選んだのか」です。技術選定、トレードオフ、失敗から学んだことは、どれも記録する価値があります。

0. まず調べてから、導入する

いきなり一式のディレクトリを作らないでください。現在のリポジトリの状態に合わせて選びます。

1. AGENTS.md ／ CLAUDE.md ／コントリビューションガイドがあれば読みます。docs/adr/、docs/decisions/、Issue テンプレートなど既存の決定記録があれば、それを踏襲し、状態と種類だけ本 Skill のフォルダー構成に合わせます。
2. 既存の決定記録がなければ、標準構成を作ります：.agents/notes/{proposed,implemented,rejected,archived} × 6 class。必要なディレクトリだけ作成し、空のディレクトリは事前に作る必要はありません。個人で作業する場合は、git を使わなくても同じ完全な構成を作ってください。単一ディレクトリに簡略化しないでください。
3. 長期運用するチームのリポジトリでは、同じ構成にプロセスを追加します：CONTRIBUTING.md ／ PR テンプレートに「重要な変更には必ずノートを添付する」と一文追加し、検証スクリプトを CI に接続します。

1. パスが分類を表す

各ノートのパスが、そのノートの識別情報です：{lifecycle}/{class}/yyyy-mm-dd-topic.md

Lifecycle（一層目のフォルダー。このノートがどの段階にあるか）：

• proposed — アイデアの段階。案はあるが、まだ実装されていない
• implemented — 実装済み。コードと同じ変更単位で同期を保つ
• rejected — 慎重に却下した提案。再発防止に役立つ場合に限り保持し、それ以外は一式を削除する
• archived — 完了済みで、今後の参照価値が低い implemented の記録。凍結し、編集不可

Class（二層目のフォルダー。次の6種類のみ。追加する場合は検査スクリプトも変更してください）：

• feature 新機能 — ユーザーまたはモデルから見える選択（自明でない動作も含む）
• bug-fix 不具合修正 — 何を修正したか、または振り返りで明らかになった不足を何で補ったか
• simplification 増やさず削る — 機能は追加せず、コード、動作、または表層だけを削る
• architecture 構造の設計 — 公開するソースコードの構成、パッケージの接続方法
• process ツールとプロセス — 検査、リリース、協業の方法（コードを中心とし、実行時の動作ではない）
• testing テストの方法 — テスト戦略と基盤

refactor は独立した分類にしません。外から見える動作が変わる場合は該当する分類にし、変わらない場合は simplification にします。INDEX.md は作成しません。詳しい判定基準は references/classification.md を参照してください。

2. ファイル形式（検査スクリプトで検証します）

本文は、きっかけとなったタスクの入力言語にかかわらず、すべて簡体字中国語で記述します（コード、コマンド、固有名詞を除く）。

最初の3行は固定です：

# Agent Note: <标题>

Status: <状态>

状態は、配置先の lifecycle フォルダーと一致させる必要があります（rejected には一言で理由を添えます）。ファイル名の日付は最初に提案した日です。本文の骨組み：

• proposed：## Problem → ## Proposal → …自由なセクション… → ## Alternatives considered → ## Acceptance criteria → ## Risks
• implemented：## Problem → ## Decision（現在形） → …自由なセクション… → ## Alternatives considered → ## Consequences
• rejected：凍結した proposal 形式。結論は Status: 行に記載

代替案は必須です。実際に検討した対案だけを記録し、まずその最も強い理由を書いてから却下します。検討していない選択肢を作り上げないでください。「何もしない／現状を再利用する」は、その時点で本当に比較検討した場合に限り記載します。スクリプトが確認するのは ## Alternatives considered が存在するかどうかだけです。実際の代替案がなければ、セクション見出しを残し、本文に「なし」と記載すれば検査を通過できます。数合わせのために案を作らないでください。 implemented の ## Decision は現在形にします。ゲートが拒否するのは提案を示す見出しだけです（## Proposal ／ ## Plan ／ ## Migration plan ／ ## Acceptance criteria と、それぞれの中国語表記）。詳細は references/note-format.md を参照してください。

テンプレートは templates/ にあります。

3. 作業前に過去の決定を検索する（分散型の4つの方法）

リファクタリングや技術選定に着手する前に、過去の制約を調べ、同じ失敗を繰り返したり、以前の妥協を壊したりしないようにします。

1. 入口のコメント（存在する場合）：コードの入口に // Note: ... 见 .agents/notes/... があれば、そのリンクをたどって読みます。ない場合は、検索用のアンカーを追加せず、次の3つの方法を使います。
2. 分類ツリーを物理的に絞り込む：リポジトリ全体を検索せず、目的に応じて直接ディレクトリを選びます（アーキテクチャなら implemented/architecture/、落とし穴を避けるなら rejected/）。
3. 対象を絞った全体検索：ripgrep を使ってキーワードや仕組みの名前を検索します。必ず --hidden を指定し、archived/ を除外します：

   rg --hidden --glob '!.agents/notes/archived/**' "<机制名或关键词>" .agents/notes/
   

4. モジュールのドキュメントをたどる：サブモジュールの README に設計根拠が書かれている場合は、相対 Markdown リンクをたどって該当するノートに直接移動します。

ユーザーに尋ねる前に、まず自分で調べてください。 上記4つの方法で分かる事実をユーザーに尋ねないでください。本当の決定だけが、ユーザーの時間を使うに値します。

4. 什么时候写、什么时候改

对话里的触发信号——用户或自己说出这类话，就该动笔（文首红线清单里的机械改动除外，别拿这些短语当过度记录的理由）：

• 拍板新路线："就选 X"、"决定用 X"、"我们先用 X 顶着" → 触发 Note
• 比较中："X 和 Y 怎么选"、"为什么倾向 X" → 触发备选记录
• 同一段理由被解释了第二遍 → 该写下来了

判定与操作流：

• 既有架构重构 / 路径迁移 / 参数改动 → 【首选原地同步】：直接在持有该决定的老 Note 里修正事实（代码路径、方法签名、默认值），不另起新篇，也不要在正文追加流水账历史。## Decision 核心理由不变；理由变了就走新建。
• 写新 Note 之前 → 按模块名/关键词搜活跃笔记，当场分类（见文首「当场审计」），禁止留到以后大扫除。
• 新想法、还没动手 → 先写 proposed（为什么想这么做、考虑过哪几条路），评审完再动手。交互纪律见下。
• 施工完（proposed → implemented），同一次改动里做完：① 移到 implemented/<class>/，文件名日期不动；② Status: proposed → Status: implemented；③ ## Proposal → 现在时 ## Decision；④ ## Acceptance criteria / ## Risks 折进 ## Consequences（或现在时 ## Testing）；⑤ 删计划段。与代码同批落盘——git 场景即同一 commit/PR。
• 方案被新决策部分取代 → 两篇都留，双方加相对链接；只更新仍成立的事实。禁止归档。
• 方案被新决策完全取代 → 新 Note 接管并写入旧篇全部独特理由/备选/后果/验证缺口；入站链接改完后，能删则删，不能删（旧篇仍有独立杠杆）再 archive-agent-note.ts。指针写在新笔记里，不写进归档篇。
• 免写场景：见文首红线——快速返回清单里的，直接提交代码。

交互协议（向用户提问时）：

1. 先分 facts 和 decisions：环境里查得到的事实（代码、笔记树、rg）自己查完再问；只有真正要拍板的取舍才占用用户时间。
2. 一轮全抛：所有待拍板的问题编号列出，每题独立一行给推荐答案 ➡️ <推荐>；用户按编号批量应答（"1 yes，2 第二个选项"），不挤牙膏、不来回试探。
3. 收敛靠确认门，不靠题数上限：落笔/动手前复述全部决定，用户确认达成共识后再执行——复述中被默认掉的任何一点，用户在确认时纠偏；没确认不动手。
4. 开放决策超过五个是信号，不是配额：说明这次改动太大——拆成多篇笔记，或先交 proposed 草稿走评审，别在一次对话里硬塞。

判定细则见 references/when-to-write.md，归档与删除见 references/archiving.md。

5. 怎么写好

• ## Consequences 同时写代价和收益，不是只写"放弃了什么"。
• 自由节（package 拓扑、wire 契约、schema 等）放在 Decision 与 Alternatives 之间，保持可检索的机制名与 must / may / never 时序强调。
• 跨 Note 引用用相对 Markdown 链接 [topic](../../implemented/architecture/2026-…-….md)，不要裸数字，以便机械可校验。
• 宿主若已有此惯例，可在核心入口留一行 // Note: ... 见 .agents/notes/...；不是门禁。决定被取代时，这些注释是要同步的代码清单。
• 文风与去推导痕迹见 references/prose-checklist.md；简化机会见 references/simplification-checklist.md。
• 写完后过一遍 references/quality-gate.md 的语义自检，只向用户报缺口和写得好的地方（≤5 行），缺口给具体修法。结构靠脚本，意思靠人点头。

6. 校验与运维命令

在仓库根目录直接运行（已配置 npm script 时）：

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

脚本位于本 Skill 的 scripts/，从宿主项目根目录调用，默认检查当前目录下的 .agents/notes/。先根据已加载的 SKILL.md 路径确定 Skill 位置，不要假定宿主根目录存在 scripts/，也不要切换到 Skill 目录执行。安装不会自动配置宿主的 npm scripts。

写完或改完任何笔记后必须运行验证：有 npm script 用 npm run verify-notes，没有就用下方 npx tsx 命令——不得以「未配置校验入口」为由跳过。

项目级安装到 .agents/skills/ 时，可直接执行：

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 "项目决策看板"

安装到 .claude/skills/ 或全局目录时，用实际 Skill 路径替换上述前缀。看板打包参数为 --bundle <notes目录> <输出.html> "名字"；参数与免疫规则见 references/verification.md。

团队可将本 Skill 的 templates/verify-notes.yml 复制到宿主仓库 .github/workflows/verify-notes.yml，调整为实际安装路径，并将项目级 Skill 文件一起提交；模板在 Skill 目录内不会执行。可在 CONTRIBUTING.md / PR 模板加一句「重要改动必带一篇笔记」。

References

按需加载：

• references/note-format.md — 头块与 body 骨架展开
• references/classification.md — 6 class 判定与边界
• references/when-to-write.md — 何时新建 / 更新 / 流转（含与 DSH 判定对齐关系的说明）
• references/archiving.md — 归档与合并删除（含"未来参考价值"判定）
• references/prose-checklist.md — 行文与去泄露自检
• references/simplification-checklist.md — 简化机会自检
• references/quality-gate.md — 写后语义自检：Problem / Alternatives / Consequences / Verification 判定 + 汇报形态
• references/verification.md — 校验脚本说明