メインコンテンツまでスキップ
バージョン: Future

フィールド作成ガイドライン

新しい Entry UI フィールドを文書化するメンテナー向けのルール。

フィールドを追加するとき​

  1. src/core/web/config-schema.ts の CONFIG_FIELDS に、簡単な説明(description)、オプション(options)、最小/最大/ステップ(min/max/step)、およびリスク度(risk)を設定してフィールドを追加します。

  2. website/src/data/entryFields.ts に、最低限 shortDescription、useCases、および guidelines を含むドキュメント項目を作成します。

  3. Construct タブページと完全なフィールドリファレンスに該当するフィールドを文書化します。

  4. フィールドドキュメントのカバレッジ（網羅率）チェックを実行します:

    npm --prefix website run check:entry-fields

  5. フィールドがリスクを伴う（risky）設定である場合、復旧/トラブルシューティングノートを最低1つ以上追加してください。

フィールドごとに必要なドキュメント項目​

項目必須
一般ユーザー向けの平易な説明はい
ユースケースはい (1つ以上)
推奨デフォルト値はい
許容される値 / 範囲はい
リスクレベルはい
副作用関連する場合のみ記述
CLI 等価コマンド関連する場合のみ記述
値の例テキスト/パスフィールドには必須
トラブルシューティングノートリスクを伴うフィールドには必須

作成ルール​

  • ソースコードを読むメンテナーではなく、AI エージェントのメモリシステムを設定するエンドユーザー向けに記述してください。
  • メモリ所有権、ルーティング、コンテキストサイズ、プライバシー、Git 同期などに対する実際の効果を指定してください。
  • Engram ワークフローに即した例を優先します: Codex、Claude、Gemini、Cursor、OpenCode、個人メモリ、クライアントプロファイル、チームリポジトリなど。
  • デフォルトで高い上限を設定するよう勧めないでください。コンテキスト肥大化による性能上のトレードオフを説明してください。
  • Engram の無効化、保存場所の変更、Git 同期の変更、メモリのアーカイブ、暗号化/セキュリティに影響を及ぼし得る設定は「risky」とマークしてください。
  • リスクのある設定に対しては復旧用のコマンドを提供してください。
  • アプリ内の説明は短く保ち、詳細なガイダンスは Docusaurus に記述してください。

CI チェックカバレッジ​

website/scripts/check-entry-field-docs.mjs は以下の場合に失敗します:

  1. 表示対象の CONFIG_FIELDS キーにドキュメント項目がないとき。
  2. ドキュメント項目が存在するが、実際の CONFIG_FIELDS には存在しないフィールドを参照しているとき。
  3. フィールドドキュメントに shortDescription、useCases、または guidelines が不足しているとき。
  4. リスクのあるフィールドにトラブルシューティングノートが1つも書かれていないとき。
  5. 数値フィールドがレンダリングドキュメントで許容範囲を欠いているとき。

次のステップ​