knowledge-cards

Imported from xtone/ai_development_tools (knowledge_sharing/skills/knowledge-cards/SKILL.md). Install upstream with npx skills add xtone/ai_development_tools --skill knowledge-cards. Copyright stays with the author.

Knowledge Cards

自分の Claude Code の記録から、その週の問いへの答えを付箋（カード）として下書きし、本人が確かめてから Notion に提出する。集まったカードは週次の合成（正・反・合の整理）の材料になる。1 回 15 分以内で終えることを目標にする。

成果物は 3 つ。

• <run>/cards-<week>.md: 本人が確認・修正するカード一覧
• <work>/cards.jsonl: カードの正本（1 行 1 カード）
• Notion「ナレッジカード」DB の行と、「週次 Tips」DB の週の行への投稿者の追加

既定の動き

引数なしで呼ばれたとき、または「Claude Code の履歴をナレッジカードにまとめて」のように期間を言わずに頼まれたときは、次の条件で最後まで進める。

• 期間: 先週の月曜 0 時から日曜の終わりまで（このマシンのタイムゾーン）。cards.py week が今日から前の ISO 週を出す
• 問い: Notion の週の行の「今週の問い」。無ければ questions.json の cadence
• 出力先: ~/.claude/knowledge-cards/runs/<week>/。実行したディレクトリ（案件のリポジトリかもしれない）にはファイルを作らない。提出が終わったら消す
• 提出: 機密スキャンが 0 件になったら、Notion の「ナレッジカード」DB に提出し、週の行に投稿者として載る

期間・問い・出力先はユーザーに聞かない。途中でユーザーに聞くのは次の場合だけにする。

1. 要確認の語でセッションを外したとき（Phase 1。業務用語かどうかの確認）
2. 提出前の自己確認（Phase 3。必ず 1 回聞く。自動提出はしない）
3. Notion MCP が使えないとき（Phase 5。代わりの手順の案内）

ユーザーが期間を言葉で指定したとき（「先々週」「月曜から金曜」「10/5 から」など）だけ、--week --since --until に直して使う。

実名運用の約束

カードはプロジェクト名と著者名を実名のまま全社エリアの Notion に置く。始める前にユーザーに 1 度だけ伝える。

• カードは自分の作業について書く。他人の作業や判断を評価する内容は書かない。failed はプロセスの話として書く
• 提出前に本人がカードを編集・削除できる。削ったことは記録しない。自動提出はしない
• 合成レポートはパターンを並べる。個人別の件数ランキングは出さない
• この仕組みは課題の抽出とアイデア創出のためのもので、人事評価には使わない
• Notion のページは全社エリアにある。エンジニア以外も読む前提で書く

カードにしない話題

人事評価・処遇（評価、査定、給与、賞与、昇格要件、1on1 など）と、Xtone・PKSHA の経営（経営会議、役員、決算、業績、事業計画、M&A、組織変更など）に関する話題は、カードにしない。経営層のメンバーが使ったときに、社内秘の情報が全社エリアに出ないようにするため。

• extract_sessions.py は、prompt または commit・PR のタイトルがこの話題に当たるセッションを、まるごと抽出から外す（prompt、commit、PR、ツールの利用回数、Bash の例）。判定は期間の外も含めたセッション全体で行う（期間の前に評価の話をしたセッションの続きも外れる）。memory も当たるものは外す。出力の excluded には件数だけが入る
• 判定に使う語が 1 つも読めないと、抽出と検査はエラーで止まる（フィルタ無しでは動かない）
• 語は 2 段ある。強い語（patterns。人事評価、取締役会など）に当たったセッションは必ず外れ、戻せない。要確認の語（review_patterns。昇格、退職、IR など、業務用語でも使う語）に当たったセッションも既定で外れるが、本人が人事・経営の話ではないと確認したものだけ戻せる（Phase 1）
• 話題の判定に使う語は <plugin-dir>/confidential_topics.json。自分だけ足したい語は ~/.claude/knowledge-cards/confidential_topics.json に同じ形式で置く（コミットされない）
• 抽出をすり抜けた材料でも、この話題のカードは書かない。cards.py validate は、claim・文脈・プロジェクト名・根拠の抜粋のどれかが当たるカードをエラーにする。言い換えて通そうとせず、カードごと消す。要確認の語のエラーだけは、本人に聞いて「人事・経営の話ではない」と言われたときに限り --allow-term <語> で通してよい。強い語は通せない

引数

$ARGUMENTS を次のように解釈する。指定が無いものは既定値を使う。

以下、このスキルのディレクトリを <skill-dir>、プラグインのディレクトリ（<skill-dir>/../..）を <plugin-dir> と書く。スクリプトはすべて python3 -I で実行する。

作業ファイルは次の 3 か所に置く。どれも Phase 0 の cards.py workdir が作り、パスを出力する。

--out を指定したときは、<run> がそのディレクトリ、<work> が <out>/.work/ になる（<state> は変わらない）。

Phase 0: 準備

1. 開始時刻を控える（完了報告で所要時間を出す）
2. 対象週を決める

python3 -I <skill-dir>/scripts/cards.py week [--week <week>]

出力の week、monday、sunday、title を以降で使う。--since の指定が無ければ monday、--until の指定が無ければ sunday を使う。--since に 14d のような日数を指定したときは、--until も指定が無ければ付けない。ユーザーが「月曜から金曜」のように期間を言葉で指定したら、それを --since と --until の日付に直す。

3. 作業ディレクトリを作る

python3 -I <skill-dir>/scripts/cards.py workdir --kind cards --week <week> [--out <out>]

出力の run、work、state を <run>、<work>、<state> として使う。--out を渡したときは、そのディレクトリが git 管理下で .gitignore に .work/ が無ければ追加を提案する。

出力に legacy があれば、旧版が実行ディレクトリに作った cards/.work/ が残っている。取り込むのは提出済みの記録（submitted.jsonl）だけで、migrated にその件数が出る。許可リスト allow.txt と投稿者 notion-user.json は、実行ディレクトリのファイルを信用しないので取り込まない（許可リストは必要になったらまた足し、投稿者は Phase 5 で解決し直す）。完了報告で、legacy のディレクトリ（prompt の抜粋を含む）は不要になったので消してよいこと、リポジトリにコミットしないことを伝える。自分では消さない。

4. 問いを決める。--questions があればそれを使う。無ければ、Notion MCP が使えて --no-notion でないとき、references/notion-submit.md の「2. 週の行を確保する」の query だけを実行して 今週の問い を読む（行が無くてもここでは作らない）。それも無ければ cadence に従う

python3 -I <skill-dir>/scripts/cards.py plan --week <week> [--ids <問いのID>]

5. ユーザーに段取りを 1 行で伝える（対象週、期間、問い、提出の有無）。確認は求めずにそのまま Phase 1 に進む

Phase 1: 抽出

python3 -I <skill-dir>/scripts/extract_sessions.py --since <since> [--until <until>] [--tz <tz>] [--projects <list>] [--include-sessions <work>/include-sessions.txt] --out <work>/sessions.json

日付は --tz（既定はこのマシンのタイムゾーン）のその日の 0 時として解釈し、--until の日は終わりまで含む。期間で絞られるのは prompt、ツールの利用回数、Bash の例、commit と PR。memory は期間で絞らない（更新日 modified を見て判断する）。

出力の excluded に、カードにしない話題として外したセッションの数が入る（中身は出ない）。完了報告でその件数だけを伝え、外したセッションの中身をユーザーに聞いたり推測したりしない。

excluded.review が空でなければ（要確認の語で外したセッションがあれば）、本人に確認する。

1. review を「プロジェクト × 当たった語（words。そのセッションで当たった要確認の語のすべて）」でまとめ、グループごとにセッション数と期間を出す。prompt の中身は出さない（review にも入っていない）。review_memories（要確認の語で外した memory の名前と語）も同じように示す
2. AskUserQuestion（multiSelect）で、「人事評価・処遇や経営の話ではない」グループを選んでもらう。例: 「ourpick-mt-proto の『昇格』12 件（仮判断の昇格などの業務用語か）」。迷うものは選ばないよう添える。グループが 4 つを超えるときは質問を分ける
3. 選ばれたグループのセッション id を <work>/include-sessions.txt に、# <プロジェクト> の <語> は業務用語（本人確認 <日付>） のコメント付きで書く。memory を戻すときは memory:<project>/<name> の行を書く
4. --include-sessions <work>/include-sessions.txt を付けて抽出をやり直す。戻したセッションで解除されるのは、本人に示した語だけ。強い語に当たったセッションと memory は、このファイルに書いても戻らない

出力には、期間内の prompt（session_id 付き）、ツール・スキル・MCP の利用回数、Bash の例、commit と PR のタイトル、memory、ハーネス構成（名前だけ）、匿名化辞書（vocabulary）が入る。秘密情報は伏せ字済み。

Phase 2: 下書き

1. references/card-writing.md を読む
2. 「カードにしない話題」に当たるものは、材料に残っていても書かない
3. 問いごとに、plan の text と draft_hint、card-writing.md の「問いごとに見る場所」に従って sessions.json の該当部分を読み、カードを書く。1 問 1〜3 枚、材料が無ければ「該当なし」を 1 枚
4. カードを <work>/cards.jsonl に 1 行 1 枚で書く。形式は次のとおり

{"card_id": "<week>/<問い>/<メールの@より前>/001", "question_id": "Q2", "week": "<week>", "week_range": ["<monday>", "<sunday>"], "author_email": "<git config user.email>", "project": "<プロジェクト名>", "claim": "20〜80 字の結論", "context": "2〜3 文", "polarity": "failed", "confidence": "observed", "evidence": [{"type": "prompt", "ref": "<session_id>@<time>", "excerpt": "伏せ字済みの抜粋"}], "tags": ["prompt"], "sensitivity": "internal", "status": "draft", "notion_url": null}

author_email は git config user.email から取る。project は sessions.json のプロジェクト名をそのまま使う。

5. 検査する。エラーが 0 になるまで直す。「confidential topic」のエラーはカードを消して直す

python3 -I <skill-dir>/scripts/cards.py validate <work>/cards.jsonl

6. 確認用の Markdown を出す

python3 -I <skill-dir>/scripts/cards.py render <work>/cards.jsonl --out <run>/cards-<week>.md

Phase 3: 自己確認

1. 問いごとの枚数と、各カードの claim を一覧で表示する。<run>/cards-<week>.md を開けば直せることも伝える
2. AskUserQuestion で聞く: 「このまま進める」「ファイルを直したので読み直す」「中止する」
3. 「読み直す」なら、Markdown を正本に戻してから検査し、再び 1 に戻る

python3 -I <skill-dir>/scripts/cards.py parse <run>/cards-<week>.md --base <work>/cards.jsonl --out <work>/cards.jsonl
python3 -I <skill-dir>/scripts/cards.py validate <work>/cards.jsonl
python3 -I <skill-dir>/scripts/cards.py render <work>/cards.jsonl --out <run>/cards-<week>.md

4. 「中止する」なら、作ったファイルの場所を伝えて終える

消したカードと 状態: dropped のカードは提出しない。ユーザーが文面を直したカードは、そのまま尊重する（Claude が書き戻さない）。

Phase 4: 機密ゲート

python3 -I <skill-dir>/scripts/scan_sensitive.py <run>/cards-<week>.md --vocab <work>/sessions.json --tier <tier> [--allow-file <state>/allow.txt]

終了コードが 1 なら、検出箇所を <run>/cards-<week>.md で書き換え、Phase 3 の 3（parse → validate → render）を通してから再実行する。検出語が一般語で伏せる必要が無いと判断できるときだけ、<state>/allow.txt に理由のコメント付きで追記する。社内で公知のホスト名（社内ツールのドメインなど）も同じ扱い。秘密情報（トークン、メール、組織 ID、ホームパス）は許可リストに入れない。

スキャンが 0 件になるまで Phase 5 に進まない。

Phase 5: 提出

--no-notion なら飛ばす。--dry-run なら、週の行の検索結果と cards.py to-notion の出力を表示し、Notion にも submitted.jsonl にも書かずに完了報告へ進む（週の行が無ければ --week-url には仮の値を入れて表示だけ行う）。

それ以外は references/notion-submit.md の手順に従う。

1. スキーマを確認する
2. 週の行を確保する（無ければ作る）
3. 投稿者を解決する（Notion MCP の接続ユーザー。決まらなければ me）
4. 足りない選択肢（プロジェクト名・タグ）を cards.py options で調べて、データソースに足す。MCP は選択肢に無い値を自動では足さず、提出が全件失敗する
5. cards.py dedupe → cards.py to-notion → create-pages → cards.py mark-submitted
6. 週の行に投稿者を足す

Notion MCP が使えない、または接続されていないときは、同じ文書の「MCP が使えないとき」の手順（notion_submit.py と NOTION_TOKEN）を案内する。トークンをチャットに貼らせない。

Phase 6: 後片付け

Phase 5 で全件の提出（mark-submitted まで）が終わったら、その回の作業ディレクトリを消す。prompt の抜粋が手元に残らないようにするため。

python3 -I <skill-dir>/scripts/cards.py cleanup <run>

cleanup は ~/.claude/knowledge-cards/runs/<週> と synthesis/<週> 以外を消さずにエラーで止まる。次のときは消さずに残し、完了報告で <run> のパスを伝える。

• --dry-run、--no-notion、確認で「提出しない」を選んだとき、途中で止まったとき、提出に失敗したカードがあるとき（直して再実行するのに使う）
• --out を指定したとき（cleanup が拒否する）

<state> は消さない。

完了報告

最後のメッセージに次を入れる。

• 対象週と問い、問いごとのカード枚数（提出した数、除外した数）

• Notion の週の行の URL（--dry-run / --no-notion のときはその旨）

• Notion に選択肢として足したプロジェクト名・タグ

• 機密スキャンの結果（0 件）と、許可リストに入れた語とその理由

• カードにしない話題として抽出から外したセッションの数（excluded.sessions。中身には触れない）と、本人の確認で戻したセッションの数（excluded.released）、--allow-term で通した語

• 開始から終了までの所要時間（参加者が週の行の「備考」に書けるように）

• 投稿者を自動で足せなかった場合は、その旨と手順

• 作業ディレクトリを消したか。残したときはそのパスと、個人の記録（prompt の抜粋）を含むので共有リポジトリにコミットしないこと