コンテンツにスキップ
ALNEAS Ecosystem

ALNEAS共通文書ポリシーの適用

ALNEAS共通文書ポリシーの適用

Section titled “ALNEAS共通文書ポリシーの適用”

背景と目的

Section titled “背景と目的”

このページは、現在の共通規約を適用するための日本語案内です。規範全文は英語の共通ポリシー、具体的な作成手順はdocument-authoringスキルを参照してください。英語正本の細則を省略した日本語案内だけで準拠を判断しません。

対象はEAOS、Appkit、SiteKitと、このポータルです。SiteKitは旧称Web Frameworkからリネーム中のため、表示名だけでパッケージ名・公開URL・公開済みバージョンを推測しません。

構成図

Section titled “構成図”
flowchart LR
  Shared[Shared policy and skill] --> Instructions[Project AGENTS references]
  Instructions --> Sources[Project README guides and English JSDoc]
  Sources --> Manifest[Approved public manifest]
  Manifest --> Portal[github-docs ingestion]
  Japanese[Portal-owned Japanese translations] --> Portal
  Portal --> Publish[Public build and verified publication]

トレードオフと判断

Section titled “トレードオフと判断”

正本と一方向の取り込み

Section titled “正本と一方向の取り込み”
  • 各プロジェクトは、実装・公開exports・英語ガイド・英語JSDocとGitHub/npm向けREADMEを管理します。
  • github-docsは、共通ポリシー・スキル・指示雛形、全体案内・ナビゲーション・索引、ポータル日本語翻訳、生成ページと公開確認を管理します。
  • 英語の修正は所有元へ、日本語翻訳の修正はポータル側の翻訳ソースへ戻します。生成APIページを直接修正しません。
  • Privateソース・顧客情報・運用記録・秘密情報・未承認の草稿は公開manifestと公開配布物へ含めません。公開向けの説明を出す場合も、承認済みの内容だけを選びます。

文書の目的を分ける

Section titled “文書の目的を分ける”

Tutorialは初心者の導入、How-toは目的別の作業手順、Referenceは正確な仕様、Explanationは背景と設計判断を扱います。API仕様、利用ガイド、AIの操作指示を混同しません。llms.txtは詳細文書への索引であり、型や契約を重複定義する場所ではありません。

GitHub・npmのREADME

Section titled “GitHub・npmのREADME”

READMEはfrontmatterを付けない通常のMarkdownとし、最初の5つのH2を次の順序にします。

  1. Elevator Pitch：誰の何を解決するか。
  2. Why & Value：存在理由と利点。既存のWhy & Value Propositionも同じ区分として扱います。
  3. Key Highlights：3〜4件の特徴。
  4. Quickstart：実行可能な導入コマンドと最小例。
  5. Next Steps：ガイド・公開exports・API・設計などへのリンク。

パッケージのQuickstartでは、インストール対象のパッケージ名とimportの機能別subpathを分けます。公開前の検証には正確なローカルtarballを使えますが、未公開の名前を公開済みとして案内しません。必要なpeer・CSS・provider・ホスト設定を説明します。ライセンスや配布条件などの詳細を入口の整理で落としません。

npm配布物の外やGitHubに載らない生成ディレクトリへの相対リンクは、正本のHTTPSリンクに直します。公開前には実tarballのREADMEとリンク先も確認します。ローカル修正・GitHubへのpush・npm公開は別の状態であり、公開後に行き先のREADMEと正本を比較します。

各プロジェクトはreadme-policy.jsonで対象を明示し、bun run docs:readmesを文書検証に組み込みます。構造・import名・リンク検査の成功だけで、説明の正確さ、完全な前提条件、例の動作、JSDoc網羅性まで保証しません。

生成ドキュメントの鮮度

Section titled “生成ドキュメントの鮮度”

READMEからのポータルページ、exports参照、manifest、AI索引、consumer向けメタデータなどの生成物は、一時出力へ再生成して現物と比較します。変更・欠落・余分な出力、生成エラー、出力先指定の無視、timeoutは失敗として扱い、検証中に通常の出力を修復しません。

所有元の生成処理を一時出力に対応させ、実際のコマンドと全出力を設定して、既存の文書・CIゲートに接続します。共通チェッカーをコピーしただけでは接続完了とはみなしません。正常な更新は通常の生成コマンドで行ってから差分をレビューし、鮮度検査を実行します。共通の導入手順を参照してください。

公開APIとJSDoc

Section titled “公開APIとJSDoc”

対象は、サポートするpackage exportsから到達できる公開宣言です。単にTypeScriptでexportされている内部モジュールを公開契約とみなしません。正本の宣言に英語で記述し、再exportと互換entryは正本を参照します。

  • 目的と実際の挙動を1文で説明し、全ての引数・型引数・公開メンバーの意味、制約、単位、省略時の挙動を記述します。
  • 戻り値は非constructorの呼び出しに記述します。非同期の解決結果、null・空値、所有権、voidの完了も区別します。
  • 実際に発生する同期例外とPromiseのreject、および意味のある伝播エラーを条件付きで説明します。存在しないエラーや一律の成功保証を作りません。
  • runtime・peer・CSS・provider、認可、副作用、永続化、cleanup、キャンセル、並行性、retryと冪等性の責務を明示します。
  • 公開callable・class・componentには、正確な公開importと定義済み入力を持つ例を付けます。必要なホスト処理を成功するだけの架空adapterに置き換えません。
  • 型はTypeScript宣言を正本とし、rendererが表示しない情報は対応する説明欄や正本ガイドへ残します。非推奨APIには理由と移行先を記述します。

細則と例外条件は、英語正本の「Public API JSDoc requirements」を確認してください。所有元で実装・exports・既存テストと照合し、例を型検査してからAPIを再生成します。

ポータルと日本語翻訳

Section titled “ポータルと日本語翻訳”

GitHub/npm READMEから、所有元でメタデータ付きのポータル用ページを生成します。導入文を別々に手で維持しません。AppkitはCore・Reactの2パッケージを機能別に案内し、現在のtoolsルートはmanifestに従って維持します。

日本語ガイドの翻訳ソースはsrc/data/translations/pages/、APIの説明辞書はsrc/data/translations/api-ja.jsonで管理します。識別子・型・import・コード例は変更しません。未翻訳部分は英語へフォールバックします。プロジェクト固有の日本語UIやruntime資産は、ポータル翻訳とは別の所有物です。

検証と公開

Section titled “検証と公開”

共通規約は正本からbun run standards:syncで公開用へ同期し、bun run standards:checkで一致を確認します。取り込みではmanifest・frontmatter・所有元の境界・リンク・秘密情報などを確認し、公開ビルドではinternal文書を読み込みと検索の前に除外します。

ビルド成功は公開完了やAPI網羅性の証明ではありません。承認された公開操作の後、対象URL・HTTP応答・内容を確認します。ホスト側の認可や実環境での動作は、それぞれの契約と検証で確認します。

関連資料

Section titled “関連資料”