メインコンテンツまでスキップ

パターンの追加・更新

パターンは説明と実装を一組で管理します。文書では設定値や構造の意味を理解できるようにし、ZIPには利用・検証に必要なファイルをそろえます。

Codexで移行・文書作成を自動で進める場合は、オートフローの手順を参照し、$pattern-autoflowを使います。通常の作成・レビュー基準は、このページと関連する運用文書に従います。

配置を決める​

<分野>/<分類>/<パターン>の3階層を決め、説明と実装の両方に同じパスを作ります。名前は英小文字を基本に、複数語はハイフンでつなぎます。数字は先頭以外で使えます。

docs/<分野>/<分類>/<パターン>/
index.md
images/ # 必要な説明用PNGがある場合だけ作る
patterns/<分野>/<分類>/<パターン>/
README.md
... # コード・設定・依存関係・検証ファイル

追加手順などの運用文書はdocs/project/に置き、対応実装を要求しません。分野名にprojectを使わないでください。

プロジェクト直下のscripts/は、配置確認・文書検証・ZIP生成などプロジェクト全体の共通処理に限定します。個別パターン専用のスクリプトはpatterns/<分野>/<分類>/<パターン>/内に置き、ZIP単体で実行できるようにします。ルートから実行することやCIで使うことだけでは、共通処理にはなりません。追加前に既存の共通処理や対象ツールのコマンドで対応できるか確認します。

プロジェクト直下のtests/も、管理処理や掲載サイトなどプロジェクト全体の共通機能を確認するテストと、その補助処理・fixtureに限定します。個別パターン専用のテストは対象パターン内に置き、ZIPに含めます。共通機能のテストには検証用fixtureを使い、特定の実用パターンの文言・設定・収録ファイルに依存させません。

文書と実装を作る​

文書テンプレートを文書側のindex.mdへ、READMEテンプレートを実装側のREADME.mdへコピーします。記入欄はすべて具体的な説明に置き換えます。

最初に何のパターンかを説明し、全体構造と主要ファイルの役割を示します。中心部分では、意味のまとまりごとにコードを示し、指定の意味、実際の入力と結果、他のファイルや処理との関係、採用理由を説明します。設定は親キーも含め、対象箇所が分かる形にします。

READMEはZIP単体で読む手順です。サイトの説明を複製するより、環境・依存関係・配置先・実行場所・コマンド・期待結果を明確にします。利用先で変更する値があれば、変更箇所と例を示します。

設定台帳とsetupスキルを用意する場合は、台帳の網羅性を保ちながら、質問項目を「重要」「普通」「あまり見なくてよい項目」に分類します。開始時に「重要のみ」「重要+普通」「すべて」を選べるようにし、範囲外は現在値・未設定時の既定動作を維持します。省略を個別確認済みと混同せず、範囲外を変更するときには追加確認が必要になるよう、スキル・CLI・回答検証をそろえます。

検証には対象の言語・ツールに合ったコマンドを使い、必要なテスト・設定ファイルを実装側に含めます。テスト本体の名前は統一しません。パターンのルートにci.jsonを置き、準備・検証コマンドと必要な実行環境を指定します。共通CIが自動的に対象へ追加するため、パターンごとのCIジョブ追加は不要です。READMEに環境確認、依存関係の導入、検証の手順と期待結果を書き、準備に失敗したら停止します。詳しくは検証とZIP配布を参照してください。

トップページの紹介情報​

トップページの一覧は、各パターンのindex.mdから自動生成します。タイトル・説明はtitle・description、文書へのリンクはslug、カテゴリ名は上位ディレクトリの_category_.jsonのlabelを使います。カテゴリ名の指定がなければディレクトリ名を表示します。ZIPのURLはパターンIDから生成するため、一覧用に書き直す必要はありません。

一覧だけで表示する特徴や画像は、文書先頭のpatternに指定します。

title: HTTP APIのエラー処理
description: 入力不備と内部エラーを分けて応答する構成。
slug: /backend/api/error-handling
pattern:
position: 1
actionLabel: 構成と処理の説明
features:
- label: 応答
value: エラー種別ごとのHTTPステータス

patternは省略できます。省略時もタイトル・説明・説明へのリンク・ZIPを表示し、説明ボタンは「詳しい説明を読む」とします。positionは小さい順で、省略時は0です。同じ値ならID順に並びます。featuresはlabelとvalueの配列で、ラベルの重複は認めません。

画面例が必要なら、patternの中に次を追加します。

preview:
src: ./images/screen.png
alt: 左にナビゲーション、中央に説明本文を配置した画面
width: 1440
height: 1100
caption: 文書画面の例
anchor: 完成画面

srcは同じ文書のimages/配下のPNGです。alt・width・height・captionを指定します。画像を押すと説明文書へ移動し、anchorがあればその見出しへ移動します。不要ならpreview全体を省略します。

文書と対応実装を追加・削除すると、次のビルドで一覧も更新されます。draft: trueまたはunlisted: trueの文書は一覧に載せません。トップページのTSXへパターンを追記する作業は不要です。公開済みのslugを変える場合は、従来どおり参照元への影響を確認します。

画像とダウンロード​

説明に必要な画像はimages/<内容が分かる名前>.pngに置き、![処理の流れ](./images/flow.png)のように参照します。PNG以外を改名しただけでは通りません。コード例で十分なら画像は不要です。

ZIPリンクには/downloads/patterns/<分野>/<分類>/<パターン>.zipを指定します。

[実装をダウンロード](/downloads/patterns/backend/api/error-handling.zip)

これは配置例です。ZIPはビルド時に生成されるため、手動で圧縮・配置・コミットしません。カテゴリ表示名や順序は必要な階層の_category_.jsonに指定します。サイドバーへ文書IDを手作業で追加しません。

確認して結果を残す​

ルートで実行します。

npm run check:dir
npm run check:docs
npm test
npm run typecheck
npm run build
npm run test:e2e

個別パターンはZIPを別の場所へ展開し、READMEの準備・検証手順で確認します。CIのZIP検証はPR全体の差分から変更された実装だけを選びます。文書だけの変更では省略し、共通のZIP生成・検証処理を変えた場合は全件を検証します。

npm run serveで自分の文書へサイドバーから移動し、本文・PNG・ZIPと、取得したZIPのREADMEを確認します。E2Eのサンプル成功だけで、自分の文書をレビューしたことにはしません。

確認日・環境・期待結果・実際の結果・未確認事項を文書に残し、レビュー項目を確認します。失敗・未実施・人間の確認待ちは成功と区別します。

更新では説明・実装・例・検証結果を併せて見直します。削除・改名では両側と参照元を更新し、再生成で古いZIPが消えることを確認します。

リポジトリ内の実装を正規配置へ移行する場合は、移行元の片付けまでを作業範囲に含めます。移行先・ZIPとの内容対応と単体動作を確認し、移行先へ含めない固有の記録を作業ツリー外へ保全してから、不要な移行元を取り除きます。コピー依頼・保持指定・リポジトリ外の参照元はその指定に従います。完了報告では正規配置、移行元が残っていない確認結果、保全した場合の保存先を示します。