MINARA規約
Minara へのすべての貢献が守るべきエンジニアリングとコンテンツの規則
最初にリポジトリ全体の CONTRIBUTING ガイドを読み、コントリビューションの進め方、環境設定、Pull Request の要件、ライセンス方針を確認してください。編集前に、ルートの CLAUDE.md、最寄りのパッケージガイド、変更パスに該当するすべての .claude/rules/*.md も確認します。
1. 最小の拡張ポイントを選ぶ
既存ツールを使う手順、専門知識、再利用可能な流れはスキルにします。決定的な処理、認証、バイナリやストリーム、新しい実行境界が必要ならツールを追加します。共有する型と UI は対応するパッケージへ置き、アプリ固有の動作はそのアプリに残します。
Minara の内部ツールレジストリに収まる機能へ、別の MCP 配管を追加しないでください。
2. 秘密情報をプロンプトとソースから離す
認証情報はファクトリ作成時に process.env から読みます。型付き環境変数ドキュメントのソースへ宣言を加え、.env.example と公開リファレンスを再生成してください。スキルは metadata.minara.requires_env で依存を宣言し、任意のプロバイダ認証情報がなければツールファクトリは [] を返します。
秘密情報をハードコードしたり、LLM に見えるツール引数として受け取ったりしないでください。テスト、fixture、スクリーンショット、ログにも実際の認証情報を含めません。
3. 安全境界を守る
ファイルシステムツールは apps/agent/src/tools/_security/sandbox.ts を通してパスを解決します。サブプロセスは既存のコマンドガードと OS 隔離を使います。これらを迂回する別のヘルパーを作らないでください。
資金を動かすツールは isFundMoving: true と controlPolicy.confirm のプレビューを宣言します。共通の権限ゲートが確認を担当し、ハンドラは承認済みの要求だけを実行します。この領域を変える前に、最も近い既存ツールと資金移動ルールを確認してください。
4. TypeScript の ESM 互換性を保つ
TypeScript ソースの相対 import には .js 拡張子を付け、型だけの import には import type を使います。
import { createThing } from "./thing.js";
import type { ToolEntry } from "../core/tool-registry.js";5. スキル ID はソースからコピーする
過去の経緯により、スキル ID にはドット、ハイフン、アンダースコアが混在します。ディレクトリ名から推測せず、有効な SKILL.md の metadata.minara.id をコピーしてください。
rg "id:" apps/agent/src/skills/builtin/*/SKILL.md組み込みローダーが走査するのは builtin/ の直下だけです。パッケージを追加または削除したら、apps/agent/tests/unit/skills/builtin-catalog-guard.test.ts の ID も同時に更新します。
6. 公開契約とドキュメントを同期する
HTTP ルートを変えたら、ルート仕様と生成済み API/OpenAPI を更新します。CLI または REPL コマンドを変えたら、reference/cli/ の対応ページを更新します。新しいツールはツールセットへ追加し、ツールリファレンスを再生成します。
REPL コマンドの必須引数が欠けている場合は、使用法エラーだけを返さず、対話的に案内します。コマンド名は /agent-run のように平坦なハイフン区切りにします。
手書きの公開ドキュメントは英語、中国語、日本語、韓国語で同時に提供します。四つの兄弟ファイルを一緒に更新し、内部リンクは /docs/features/portfolio のようにロケールを含めません。
7. 適切な境界でテストする
まず単体テストを使います。SQLite、CLI、ゲートウェイ、実際のローカル部品の境界には統合テストを使い、完全なユーザーフローには E2E テストを使います。テストは本番認証情報なしで動作し、ローカル状態を隔離しなければなりません。
対象を絞ったテストから始め、型チェックと影響範囲の広いスイートへ進みます。Pull Request に test.only や不安定な時間依存の前提を残さないでください。
8. 出所とライセンスを尊重する
プロジェクト条件の下でライセンスできるコード、データ、プロンプト、媒体だけを提出し、必要な表示を残してください。第三者素材のライセンスが不明または欠けている場合は、確認が終わるまで導入を止めます。
Minara.AI の専有資産、ユーザーの取引データ、モデル重み、出所と権利を説明できない生成物を提出しないでください。
変更を集中させる
- 機能変更に無関係な整理を混ぜない。
- 内部ツールレジストリに収まる機能へ MCP の仕組みを追加しない。
- シークレットをハードコードしたり、LLM から見えるツール引数として受け取ったりしない。
- 具体的な反復需要がない抽象化を増やさない。
- コードの動作を読み上げるだけのコメントを書かない。
- 起こりえない条件へのエラー処理を追加しない。
- この Node リポジトリに Python を追加しない。
.env、.minara/、sandbox/、dist/、ローカル DB をコミットしない。- OSS 以外のコンテンツを
apps/agent/src/skills/external/に取り込まない。 - 生成ドキュメントを直接編集せず、ソースを変更して再生成する。