seisoが行うこと
seisoは、AIが作成し、人やコーディングエージェントが読むプロジェクトドキュメント向けのMarkdown規約およびリンターです。リポジトリのドキュメントの一貫性と保守性を保ち、将来の変更におけるコンテキストとして使いやすくします。
このツールは、各プロジェクトが独自のドキュメントルールを考案することを求めるのではなく、共有された規約に照らしてドキュメントをチェックします。各ドキュメントはhowto、reference、adrなどの種類を宣言し、その種類に適した内容だけを含めます。
seisoは、各事実に権威ある掲載先を1つだけ設けることも促します。他のページでは同じ情報を繰り返さず、その情報源にリンクします。これにより、AIが生成したドキュメントでフィールド一覧、バージョン、ステータス、件数などが複数のファイルにコピーされた場合に、特に矛盾を減らせます。
ドキュメントの基本原則
- すべてのドキュメントは1つの種類を宣言し、その種類の目的に従います。how-toは手順を説明し、設計上の判断理由はADRに記録します。
- 各事実には1つの掲載先を設けます。他のドキュメントでは繰り返し記載せず、権威あるページにリンクします。
- 長期間維持するページには、ページ自体より速く変化する値を記載しません。バージョン、デプロイ状況、件数などが該当します。
- 文が具体的な実装の詳細を指す場合は、ポインターでファイルまたはシンボルを特定します。
- 完成したドキュメントでは、依頼者に語りかけたり、ドキュメントの作成過程を説明したりしません。
- ツールで判断できない判断事項は、理由とともに記録します。理由のない例外は、それ自体が違反です。
seisoは、これらのドキュメントルールに重点を置いています。文章が機械生成らしく聞こえるかどうかは判定せず、書式やスペルは他のツールに任せます。
seisoをインストールする
対応しているインストール方法から1つ選びます。Rust、Python、npmの各パッケージは、同じコマンドラインツールを提供します。
cargo install seiso
uv tool install seiso
# または pipx を使用:
pipx install seiso
npm install -g @scarletkc/seisoPyPIおよびnpmパッケージには、Apple siliconおよびIntel搭載のmacOS、glibcを使用するLinux x64およびarm64、Windows x64向けのビルド済みバイナリが含まれています。AlpineなどのmuslベースのLinuxディストリビューションを含むその他のプラットフォームでは、Cargoを使ってインストールします。Rustツールチェーンが利用できる場合、PyPIパッケージはこれらのプラットフォームでソースからビルドすることもできます。
ソースチェックアウトから作業している場合は、Cargoを通してコマンドを実行します。
cargo run -- <command>リポジトリを初期化する
リポジトリのルートからseisoを実行します。まず、初期設定を作成するよう指示します。
seiso initこれにより、リポジトリのルートにseiso.tomlファイルが書き込まれます。生成される設定には、推奨される除外設定とドキュメント種別のマッピングが含まれます。初期マッピングはプロジェクトの判断に代わるものではなく、リポジトリの出発点であるため、結果を信頼する前にこれらの提案を確認してください。
最初のチェックを実行する
生成された設定を確認したら、リポジトリをチェックします。
seiso checkデフォルトでは、seiso checkは安定版のルールだけを実行します。これらのルールはseisoの正式採用基準を満たしており、プロジェクトに信頼性の高い基準を提供することを目的としています。
診断メッセージは問題の発生箇所を示し、修正方法を説明します。そのため、多くの指摘はコマンドの出力を直接参照して修正できます。2つのページのどちらが事実を所有すべきかを決める場合など、人間の判断が必要な指摘では、診断メッセージが必要な判断内容を示します。
ルールとドキュメント構造を確認する
ルールコマンドを使って、seisoでチェックできる内容を確認します。
seiso rule --all
seiso rule <CODE>seiso rule --allはすべてのルールを一覧表示し、それぞれのステータスを示します。seiso rule <CODE>を使うと、個別のルールを例付きで確認できます。
ルールを実行せずにseisoのドキュメントモデルを調べるには、次を使用します。
seiso parseこのコマンドは、ツールがドキュメントをどのように解釈するかを学ぶ場合や、チェックで特定の結果が出た理由を調査する場合に役立ちます。
プレビュールールは慎重に使う
正式採用基準をまだ満たしていないルールは、プレビューとして利用できます。プレビュールールは実験的で、誤検出を報告する可能性があるため、標準のチェックでは有効になっていません。
--previewオプションを使ってローカルで試します。
seiso check --previewプレビュールールは、潜在的なドキュメントの問題を早期に見つけるのに役立ちます。ただし、READMEでは、安定版になるまでCIのゲートに組み込まないことを推奨しています。実用的なワークフローでは、必須チェックに安定版ルールを使い、任意のローカルレビューにプレビュールールを使います。
ドキュメントワークフローにseisoを導入する
- Cargo、uv、pipx、またはnpmを使ってseisoをインストールします。
- リポジトリのルートから
seiso initを実行します。 seiso.tomlにある推奨の除外設定と種別マッピングを確認します。seiso checkを実行し、報告された指摘を解決します。- 診断メッセージの内容を理解する必要がある場合は、
seiso rule --allと個別ルールの説明を使います。 seiso check --previewをローカルで試します。ただし、プレビューの指摘をCIのゲートとして使うことは避けます。
より大規模なワークフローについては、seisoのドキュメントに設定、ルールの選択、出力形式に関するガイダンスと、Claude Codeフック、pre-commit、CI統合に関するガイダンスがあります。
高度なガイダンス
事実の権威性を保つ
seisoが情報の重複や配置ミスを報告したら、その事実をどの文書が管理すべきかを判断します。正式な説明をその文書に移し、関連ページからリンクします。これにより更新が安全になり、読者にもエージェントにも信頼できる情報源が明確になります。
文書の種類を目的に合わせる
手順にはhowto、長期的に有効な事実情報にはreference、設計上の選択に至った理由にはadrを使用します。これらの目的を分けることで、1つのページが手順、参照データ、過去の意思決定の混在したものになるのを防げます。
正当な例外を記録する
リポジトリ上の判断には、機械的なルールではなく判断力が必要な場合があります。例外を残す場合は、その理由を記録してください。seisoは、説明のない例外をドキュメント上の問題として扱います。将来の貢献者やエージェントが、それが意図的なものか判断できないためです。
ルールが不明確な場合は規約を確認する
seisoの規約では、各文書種別の契約と、診断が根拠として示せる証拠を定義しています。期待される構造を理解したり、指摘事項の修正方法を判断したりする必要がある場合は、seiso rule <CODE>の出力と併せて使用してください。
まとめ
seisoは、プロジェクトのドキュメントに共有された構造と、検証に特化したツールを提供します。インストールし、seiso.tomlを生成して確認し、安定版のチェックを実行し、ルールの説明を使って人間とコーディングエージェントが信頼しやすいドキュメントに整えましょう。プレビュールールは正式採用されるまで実験的なものとして扱い、所有権と例外に関する判断をリポジトリ内で明示的に管理してください。