Last updated on

制作ナレッジのストック — 整理メモ・Skill・mixin と shell の置き場

  • Cursor
  • Agent Skills
  • Sass
  • ワークフロー
  • ナレッジ管理

よしあきは、Vite + EJS + Sass の静的サイト制作テンプレートを案件ごとに複製し、WordPress テーマへ型を移植しながら日々コーディングしている。あわせて Cursor の Agent に短文で依頼し、学びや手順を 非公開の個人用ナレッジ に溜めている。

前の記事 制作で使い回す Sass mixin 一覧（ホバー / ボタン / アイコン / reduced-motion） は、呼び出せる型（@include する mixin）のカタログだった。本記事はその ひとつ上のレイヤー — いつ・どこに・何の形でストックするか — を整理する。

読み方

  1. 2 種類の正本
  2. 置き場の地図
  3. 昇格の流れ
  4. 事例 A — Sass mixin（テキスト省略）
  5. 事例 B — shell と npm（案件セットアップ）
  6. 納品後 — テンプレ還流
  7. Cursor Agent との使い分け
  8. まとめ

2 種類の正本

ストックには、大きく 読む正本 と 呼ぶ正本 がある。

種類役割典型例Agent だけで再現しやすいか
読む正本なぜ・いつ・例外・判断整理メモ、Agent 向け手順（Skill）、プロジェクトの AGENTS 系ルール会話ごとに prose が drift しやすい
呼ぶ正本短い入力で同型の結果Sass @mixin、shell 脚本、npm run、設定ファイル正本を Read / 実行すれば差分が小さい

（補足）prose は Markdown や Skill の説明文のような自然文。drift は、セッションが変わるたびに解釈や抜けが少しずつズレていくこと。読む正本だけだと「だいたい合ってそう」でも境界条件が会話ごとに変わりうる。呼ぶ正本なら同じファイルを Read / 実行すれば差分が小さい。

Skill は地図、mixin や shell は型 — どちらか一方に寄せすぎない、という割り切りがよしあきの運用の芯だ。

  • Skill だけ — 「line-clamp を使って」「案件をセットアップして」と 提案・生成 はできる。ただし境界条件（padding と line-clamp の同一要素問題など）は会話ごとに抜けやすい。
  • mixin / sh あり — 人間も Agent も 同じファイル を @include したりターミナルで走らせたりする。レビューは diff が具体になる。

置き場の地図

非公開の個人用ナレッジと制作テンプレを、次のように分けている（名称は環境ごとに違ってよい。役割が重要）。

一次メモ        … 試行・会話・クリップ
整理メモ        … 背景・根拠・例外（人間と Agent が読む）
Agent 手順      … 短文指示の解釈・手順の束ね（Skill）
実行物          … mixin / shell / npm / config（人間・ビルド・CI が呼ぶ）
デモ / ブログ   … 目で確認できる索引（任意）

コード内で @include する系（mixin に近い）と ターミナルで走らせる系（shell に近い）は、どちらも 呼ぶ正本 だ。見た目は違うが、「同じ依頼を何度も同型に再現する」という目的は同じ。

カテゴリ再現しやすくするもの例
Sass mixin複数セレクタ（:hover + :focus-visible）、a11y、擬似要素の契約ホバー系、前記事の一覧
Sass mixin宣言のセット化text-truncate() / line-clamp($lines)
JS モジュールDOM 契約ごとのインタラクションタブ・スライダー（型として静的テンプレに残し、WP へ移植）
shell外部 API・サーバー・Secrets の順序案件検証環境の一括セットアップ
npm script定型のビルド後処理・初期化デモ削除、動画圧縮、フォント圧縮

デモページは本番コードではないが、mixin やコンポーネントの 目視索引 として効く（例: 静的テンプレのデモ一覧）。ブログ記事（公開側）も、理解の整理と外向きの入口として 任意の 5 段目 に置いている。

昇格の流れ

よしあきが目安にしている 昇格 は次の順だ。

1. 一次メモ     … まだ揺れている試行
2. 整理メモ     … なぜそうしたか・例外が必要
3. Agent 手順   … 同じ短文依頼が繰り返される
4. 実行物       … 同じ CSS セット・同じコマンド列が毎回出る
5. デモ / ブログ … 索引が欲しいとき（必須ではない）

昇格する目安

Skill（手順）に上げる

  • 「日報」「案件振り返り」「セットアップして」のように チャットの短文が固定 してきた
  • 順序・禁止事項・秘密の扱いを 毎回同じように説明 していた

mixin / shell / npm に降ろす

  • 同じセレクタセット（メディアクエリ・擬似要素・打ち消し含む）を 3 回以上書いた
  • ベース CSS と衝突する（例: リンク既定の hover-opacity をボタン mixin で打ち消す）
  • a11y や prefers-reduced-motion で省略すると問題になる
  • 案件をまたいで同じ名前で使う見込みがある
  • ターミナルで同じコマンド列を毎回打っている（プロビジョニング、Toggl 集計、資産圧縮など）

昇格しない例

  • 一度きりの判断、まだ試作中 → 整理メモまたは Skill の prose だけで足りる
  • 1〜2 プロパティの差 → CSS 変数やユーティリティクラスで足りることも多い
  • 「npm run build だけ」のような 1 行 Skill → 親 Skill や npm に吸収（Atomic Skill を増やしすぎない）

事例 A — Sass mixin（テキスト省略）

前記事 が ホバー・アイコン・reduced-motion の型なら、2026-06 に足した テキスト省略 は 昇格フロー全体 の短い縦断例になる。

段よしあきが残したもの
試行複数行省略で 3 行目が半分見える — padding と -webkit-line-clamp を 同一要素 に置いていた
mixintext-truncate() / line-clamp($lines) — 宣言セット + 「padding は親、line-clamp は子」 のコメント
デモドキュメント（テキスト省略） — 外側に padding、内側 div に @include
適用既存コンポーネントの -webkit-line-clamp 直書きを @include に置換
技術メモ制作テンプレの architecture に §1 節

Skill だけ なら「line-clamp 使って」で足りる。mixin + デモ + architecture まで残す理由は、表示崩れの境界条件 を次の案件・次の Agent セッションでも同じ構造に寄せるためだ。

mixin に降ろすかどうかの判断は 前記事の「まとめ」 と同型 — 既存 mixin で足りないか先に見る。足りなければ 擬似要素の占有 と CSS 変数の契約 をコメント付きで増やす。

事例 B — shell と npm（案件セットアップ）

mixin と 同じ「呼ぶ正本」枠 に、ターミナル系がある。

短文「案件 id … でセットアップして」

  • Agent 手順（Skill） — 何を --wordpress 付きで走らせるか、秘密をチャットに書かせないか、を解釈する
  • shell 脚本 — サーバー準備 → リポ clone → .env.deploy → Secrets 登録、の 順序を固定
  • 設定テンプレ — FTP 等の雛形をリポに置き、登録漏れを減らす

Skill だけだと、Agent が毎回 似たコマンド列を生成 しうる。脚本があると、よしあきも Agent も 同じ入口 から近づける。

npm run init（案件着手時）

  • デモページ・デモ用 JS/Sass を一括削除する 初期化脚本
  • 逆に global/mixins/ は残る — 型はテンプレに、デモだけ消える、という住み分け

ここでも 地図（Skill）と型（sh / npm） の二段構えが mixin 事例と同型だ。

納品後 — テンプレ還流

ストックは 案件の最中 だけでは終わらない。よしあきは 納品後の案件振り返り に、次の工程を足している。

  1. 案件リポを見返す — テンプレに戻せそうな mixin 候補、脚本、npm、設定、Agent 手順候補を洗う
  2. 振り返りメモに表で残す — 種類・概要・還流先・状態（候補 / 実施済 / 見送り など）
  3. 実装は別タイミング — 「還流まで」「テンプレに入れて」と明示したときだけ、静的テンプレ・WP テンプレ・手順側へ反映

記録と実装を分ける のがポイントだ。振り返りのたびにテンプレを触ると diff が膨らむ。候補の列挙 までを振り返りの既定にし、昇格は選別してからにしている。

事例 A の line-clamp は、まさに 案件横断で再利用できたからテンプレへ還流した mixin の一例だ（詳細は 前記事 と デモ — テキスト省略）。

Cursor Agent との使い分け

よしあきの実務での使い分けは次のとおり。

やりたいこと渡す・参照させるもの
コーディング規約・a11y整理メモ（汎用ルール）を @ またはマルチルートで開く
「日報」「振り返り」「セットアップ」Agent 手順（Skill）+ 短文ルール
ホバー・省略など CSS の型制作テンプレの global/mixins/ とデモ
同じコマンドを毎回shell / npm run の正本を Read または実行

AI コード FB をストック するときも同型 — 一次メモ → 汎用ルールへ昇格できるものだけ整理メモへ、という流れだ。

Agent は Skill から 手順を提案 できるが、境界条件は実行物に書いた方が再現しやすい。よしあきは、繰り返しが見えたタイミングで 地図から型へ降ろす ことを意識している。

まとめ

制作ナレッジのストックは、読む正本（なぜ・いつ）と 呼ぶ正本（mixin / shell / npm）を分け、必要に応じて昇格させる。

次に同じ問題に当たったとき、よしあき自身が先に聞く 3 問:

  1. また同じ短文依頼が来る？ → Agent 手順（Skill）
  2. また同じ CSS やコマンドを書く？ → mixin / shell / npm
  3. なぜそうしたかを残す？ → 一次メモ → 整理メモ

mixin カタログ は 呼ぶ正本の中身、本記事は その育て方と還流 だ。新しいインタラクションや手順に着手する前に、どの段階までストックすればよいかを決めてから実装に入ると、案件間で散らかりにくい。