doc

name	doc
description	ドキュメント・記録の運用の正本 (置き場判定・原則・ADR の作法)。 issue / ADR / docs / brain ノートに振り分けて保存まで実行する。 Claude Code で /doc、Codex で $doc と入力したとき、「これ残しておきたい」「どこに書くべき?」と言ったとき、 設計ドキュメント・仕様・README などドキュメントを書く・編集する前、 および実装が完了して PR を作る前の残し漏れ確認に使用する。

/doc

記録の置き場を判定し、保存まで実行する。置き場判定の正本はこのスキル。設計の判断は ADR、経緯は nozomiishii/brain#268。

原則

• 読み手は未来の自分と AI エージェント。文章の完成度より、鮮度と見つけやすさを優先する
• ドキュメントを書く・編集するときは、エンジニア特有の言い回しに染まらないための言葉遣いメモを読み、避けたい表現を使わない
• 一般知識は書かない。AI に聞けば分かることは AI に聞く。書くのは自分の環境・判断・記録など、AI が知り得ない事実だけ
• 新鮮で少量を保つ。古くなった記述は残さず消す

判定フロー

内容ごとに次で判定する。判定はこのスキルの内部ロジックで行い、ユーザーへの一問一答はしない。

• まだやってない話 (思いつき・保留・未着手の計画) → 対象 repo の issue
• 未着手の実装の design doc → 対象 repo の issue
• 着手中の実装の design doc → 対象 repo の docs/ (実装 PR で育てる)
• なぜこうしたかの記録 (決着した判断) → 対象 repo の docs/decisions/ に ADR
• 今どうなってるかの事実 (仕様・手順) → 対象 repo の docs/ (実装 PR に同梱)
• AI エージェントへの行動指針・フィードバック (呼称・進め方の好み・作業ルール) → AGENTS.md (全 repo 共通は dotfiles/home/AGENTS.md、repo 固有は対象 repo の AGENTS.md)。Claude Code に読ませる repo では CLAUDE.md から AGENTS.md を参照できる構成が必須。既存の CLAUDE.md が無ければ同じ内容を参照する symlink、既存内容があれば上書きせず @AGENTS.md import を使う
• repo に限らない学び → sibling の note SKILL.md を明示的に読み、その手順へ委譲

Claude Code の auto memory は無効化している (autoMemoryEnabled: false)。Codex の memory 状態は別設定なので、この値から推測しない。memory に永続化したくなる内容はこのフローで AGENTS.md / issue / brain に振り分ける。

design doc の置き場は着手で切り替わる。着手したら issue の内容を docs/ のファイルへ移し、実装 PR で実装と一緒に育てる。issue には移した先のリンクだけ残し、実装 PR で close する (正本は 1 つ)。マージまでに「どう作るか」の記述を削り、今どうなってるかの Reference に仕上げる。経緯として残したい判断は ADR に書く。

探すときの入口は 3 つ: repo のことは AGENTS.md から docs/ へ、経緯は issue 検索と ADR、横断は brain vault。

候補の列挙と一括確認

会話から残す候補を列挙し、判定結果を表で 1 回だけ提示する。候補には番号を振り、「番号で指定してください」と添える。

#	内容	置き場	アクション

承認で実行する。「2 と 4 だけ」のような番号での取捨選択、修正指示 (「これは issue でなく ADR」等) があれば反映して実行する。issue 作成・PR は外向き操作なので、承認前に実行しない。

実行: issue

• セッション内容は要約して本文に書く。session URL は書かない (issue が public 化した瞬間に会話全文が露出しうる。public / private を問わない)
• 既存 issue があれば新規作成でなくコメントで追記する
• タイトル: Conventional Commits (英語)、本文: 日本語

実行: ADR (docs/decisions/)

対象 repo の docs/decisions/ に 1 判断 1 ファイルで作る。ディレクトリは最初の ADR を書くときに初めて作る。

• 書くのは、議論が決着し、後で「なんでこうしたんだっけ」と聞きたくなりそうな判断だけ。それ以外は書かない
• ファイル名はタイトル (日本語の決定文) をそのまま使う。連番・日付は付けない。ファイル名に使えない文字だけ置き換える
• 20 行程度。accepted 後は編集しない。判断が変わったら新 ADR を書き、旧 ADR の Status を superseded by <新 ADR への相対リンク> にする
• 本文から決着元の issue にリンクする
• ADR や docs 間のリンクは相対 markdown リンク。wikilink は Obsidian vault の外では解決されない

テンプレート。見出しの日本語は添え書きで、慣れたら外してよい。

# <決定を 1 文で>

Status: accepted
Date: YYYY-MM-DD

## Context — 判断を迫られた状況

## Decision — 決めたこと

## Consequences — 決定がもたらすもの

実装 PR があればそこに同梱し、なければブランチを切って PR にする。セッション開始ディレクトリ以外の repo は sibling の wt SKILL.md を明示的に読み、worktree を切ってから作業する。

実行: docs/ (仕様・手順)

• Diátaxis でいう Reference (事実) と How-to (手順) だけを書く。経緯は issue と ADR に任せる
• 着手中の design doc だけは例外として置いてよい。マージまでに Reference に仕上げる
• 実装 PR に同梱する。docs 単独メンテの PR は作らない
• ファイル名は内容がわかる日本語で付ける。ファイル名に使えない文字だけ置き換える
• 手書きの index ファイルは作らない。内容がわかるファイル名が index の役割を果たす
• 更新のついでに古くなった記述を見つけたら消す

実行: brain ノート

note skill に委譲する。

PR 作成前の確認

実装を終えて PR を作る前に次を自問し、該当があれば候補として提案する。

• 後で「なんでこうしたんだっけ」と聞きたくなる判断をしたか → ADR
• 仕様・手順が変わったか → docs/ を同じ PR で更新
• design doc に「どう作るか」の記述が残っていないか → 削って Reference に仕上げる。残したい判断は ADR
• repo に限らない学びがあったか → note skill