PowerShell 学習資料 ローカルルール

このプロジェクトでだけ通る決めごと。全プロジェクトに通ることは共通ルールに置く

📅 作成: 2026-08-22 / 更新: 2026-10-11

共通ルールと違うところ: commit と push

項目内容
見出し共通ルールの「修正は1点ずつ、確認を重視」「重大な操作の確認方法」
違い意味のまとまりが1つ終わるたびに、指示を待たずに commit し、続けて push する
なぜ公開資料を少しずつ直していくプロジェクトで、1点ごとに指示を挟むと進みが止まるため。push しても GitHub Pages が更新されるだけで、取り返しはつく
どこまでこのリポジトリだけ。共有環境 (PlayWright 等)への commit は対象外で、従来どおり指示を待つ
変えないもの載せるファイルを名指しする・git add -A を使わない・最初のコミットの点検・メッセージの書き方

ファイル形式

資料は HTML で直接作成する (docs/NN-タイトル.html)。HTML が唯一の原本。

Markdown は生成物

GitHub は .html をレンダリングしないため、同じ内容の .md を HTML から生成する。

html2md --dir notes --dir docs

Why: 資料を2箇所で保守すると必ず食い違う。HTML を原本と決め、Markdown は毎回作り直す派生物として扱う。

スクリプトの置き場所

ps1 / cmd スクリプトは src/scripts/<用途>/ に置く。ここはコミット対象。

src/scripts/
├── figures/    # docs の SVG 図を PNG に書き出す
└── pptx/       # PNG と HTML から pptx を生成する

Why: スクリプトは資料と同じく再現に必要な資産なので、履歴に残す必要がある。etc/ は gitignore 対象なので置くと失われる。

資料を追加したら計画の状態を更新する

docs/NN-*.html を新規作成・完成させたら、同じ作業の中で docs/ZZ-構成.html の状態を更新する。

更新する箇所は2つ:

  1. 「ファイル一覧」表の該当行のバッジ (<span class="badge b-none">未着手</span> → <span class="badge b-good">作成済</span>)
  2. 「基礎編／実践編の詳細」の該当 h2 見出しの末尾バッジ

Why: 計画と実体がずれると、次にどこから再開すればよいか分からなくなる。状態の更新を別作業にすると必ず忘れる。

付録は A1- A2- の連番にする

本編は docs/NN-タイトル.html (01〜10)、付録は docs/AN-タイトル.html (A1・A2)とする。

Why: 本編は順に読むもの、付録は必要なときに引くもので、役割が違う。番号を連番で続けると「11章がある」と誤解される。

A1.2 のコマンド索引は自動生成する

docs/A1-逆引き.html の A1.2 (コマンドから引く)は手書きしない。

Why: 69 種 × 10 章の対応表を手で維持すると、章を追加するたびに陳腐化する。A1.1・A1.3・A1.4 は内容の判断が要るため手書きのまま。

Playwright の対象ファイルは targets.ts だけに書く

tests/targets.ts が唯一の一覧。capture-figures / export-outline の2つの spec はどちらもここから読む。

Why: spec ごとに一覧を持つと追記漏れが起きる。実際に export-outline だけ追記を忘れ、付録の構造 JSON が生成されず pptx を作れなかった。

共通ルールと違うところ: 見出しの番号

項目内容
見出し共通ルールの「HTMLデザインルール」＞「クラス名」の「章の連番は html2md が振る。HTML 側に番号を書かない」
違いHTML の見出しに資料番号付きの番号を書く。タイトルバーの h1 は 01. PowerShell の生まれた経緯、章の h1 は 01.1 Windows Command Shell の限界
なぜ資料をまたいで「01.2 を参照」と書くため。html2md が振る番号は資料ごとに 1 から始まり、資料番号を持たない
引き受けることMarkdown では html2md の番号と重なり、## 1. 01.1 Windows Command Shell の限界 になる

SVG 図の追加

できるだけ SVG 図をいっぱい付ける。

各ファイルにフロー図・比較図・概念図を複数枚埋め込む。描き方は docs/rules/html-design.md および共通ルールの「SVG図」節に従う。

callout には本文に無いことだけを書く

本文で述べた結論を callout で言い直さない。言い回しを変えても、読者は同じ話を2回読んだと感じる。

入れてよいもの

種類例
警告・注意「/MIR はコピー先の余分なファイルを削除します」
落とし穴「Select-Object を通すと型が変わります」
意外な事実「実行ポリシーはセキュリティ機能ではありません」
補足「PowerShell が初めての人へ」 (読者B向け)
判断事実から導いた「だからこうする」。本文に書いていない場合のみ

入れてはいけないもの

判定方法

callout を消しても本文だけで意味が通るなら、その callout は不要。

逆に、本文側が結論まで書いてしまっている場合は、本文を「何が起きるか」の提示に留め、判断は callout に集約する。

✗ 本文  : PowerShell の関数はコマンドとして呼びます。
   callout: 関数は「コマンド」であって「メソッド」ではありません。…

✓ 本文  : ここが経験者ほど間違える箇所です。しかもエラーが出ないまま、意図と違う値が渡ります。
   callout: 関数は「コマンド」であって「メソッド」ではありません。…

Why: 本文と callout はどちらも「地の文」として読まれる。同じ主張が並ぶと、読者は情報量の割に長い資料だと感じる。

等幅フォントは BIZ UDゴシックを使う

code / pre / SVG 内のコード表記は、バックスラッシュを ¥ で描くフォントを使う。

font-family: "BIZ UDゴシック", "ＭＳ ゴシック", Consolas, "Cascadia Mono", monospace;

実測での比較:

フォント\ の表示等幅
Consolas / Cascadia Mono\✅
BIZ UDゴシック¥✅ 採用
ＭＳ ゴシック¥✅ 見た目が古い
MS UI Gothic¥❌ プロポーショナル

Why: 日本語 Windows のコンソールは \ を ¥ で表示する。資料の表示を実機に合わせたほうが、読者が画面と資料を照合しやすい。

バージョン差はバッジで明示する

資料は Windows PowerShell 5.1 と PowerShell 7 (pwsh) の両方を対象にする。どちらか一方でしか動かない、または挙動が異なる内容には、その場でバッジを付ける。

.b-ps7  { background: linear-gradient(100deg, #1a5fa8, #4d9ae0); }  /* pwsh 7 以降 */
.b-ps51 { background: linear-gradient(100deg, #5b2d82, #9a6bc4); }  /* 5.1 固有 */
<span class="badge b-ps7">pwsh 7</span>三項演算子 <code>$a ? $b : $c</code> が使える
<span class="badge b-ps51">5.1</span>BOM がないと日本語が壊れる

Why: 読者の実行環境が 5.1 か 7 か分からない。コピペして動かなかったとき、原因がバージョン差だと即座に判別できる必要がある。