Skip to content

CONTRIBUTING.ja-JP.md

Latest commit

 

History

History
296 lines (205 loc) · 23.8 KB

CONTRIBUTING.ja-JP.md

File metadata and controls

296 lines (205 loc) · 23.8 KB
Raw

Open Design ぞのコントリビュヌション

コントリビュヌションを怜蚎しおくださりありがずうございたす。OD は意図的に小さく保っおいたす — 䟡倀の倧郚分はフレヌムワヌクコヌドではなくファむルSkill、Design System、プロンプトフラグメントにありたす。そのため、最も効果の高いコントリビュヌションは通垞、フォルダ 1 ぀、Markdown ファむル 1 ぀、たたは PR サむズの adapter です。

このガむドでは、各皮コントリビュヌションの察象堎所ず、PR がマヌゞされるために満たすべき基準を正確に説明したす。

English · Português (Brasil) · Deutsch · Français · 简䜓䞭文 · 日本語 · 한국얎 · àž àž²àž©àž²à¹„àž—àž¢

午埌䞀回で出荷できる 3 ぀のこず

やりたいこず 実際に远加するもの 配眮堎所 芏暡
OD に新しい皮類の artifact をレンダリングさせる請求曞、iOS Settings 画面、ワンペヌゞャヌ  Design template design-templates/<your-template>/ SKILL.md ずレンダリング asset を含むフォルダ 1 ぀
タスク䞭に゚ヌゞェントが呌び出す機胜を远加する Skill skills/<your-skill>/ SKILL.md ずオプションのリ゜ヌスを含むフォルダ 1 ぀
OD に新しいブランドのビゞュアル蚀語を話させる Design System design-systems/<brand>/ 1 ぀のパッケヌゞmanifest.json、DESIGN.md、tokens.css
新しい coding-agent CLI を接続する Agent adapter apps/daemon/src/runtimes/defs/ 定矩 1 ぀ず registry entry 1 ぀
機胜远加、バグ修正、open-codesign から UX パタヌンを移怍 コヌド apps/web/src/、apps/daemon/ 通垞の PR
ドキュメント改善、Français / Deutsch / äž­æ–‡ ぞの翻蚳、タむポ修正 ドキュメント README.md、README.fr.md、README.de.md、README.zh-CN.md、docs/、QUICKSTART.md PR 1 ぀

アむデアがどのカテゎリに該圓するか分からない堎合は、たず discussion / issue を䜜成しおください。適切な堎所をご案内したす。

ロヌカル環境セットアップ

完党なセットアップ手順は QUICKSTART.md にありたす。コントリビュヌタヌ向けの芁玄

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable           # packageManager で指定された pnpm を遞択
pnpm install
pnpm tools-dev run web    # daemon + web フォアグラりンドルヌプ
pnpm typecheck            # tsc -b --noEmit
pnpm --filter @open-design/web build  # 必芁に応じお web パッケヌゞをビルド

Node ~24 ず pnpm 10.33.x が必芁です。nvm / fnm はオプション。䜿甚する堎合は nvm install 24 && nvm use 24 たたは fnm install 24 && fnm use 24 を実行しおください。macOS、Linux、WSL2 が䞻芁プラットフォヌムです。Windows ネむティブもサポヌトされおいたす — 䞀般的なセットアップ時の萜ずし穎に぀いおは docs/windows-troubleshooting.md を参照しおください。

OD 自䜓の開発に agent CLI は PATH 䞊に䞍芁です — daemon は「no agents found」ず衚瀺し、Anthropic API · BYOK パスにフォヌルバックしたす。このパスが最も高速な開発ルヌプです。

新しい Design template の远加

Design template は design-templates/ 配䞋のフォルダで、ルヌトに SKILL.md を持ち、Claude Code の SKILL.md 芏玄ずオプションの od: 拡匵に埓いたす。Templates ギャラリヌに衚瀺する artifact の圢ずレンダリングリ゜ヌスをたずめたす。

→ 詳现は docs/skills-contributing.md を参照

Design template フォルダ構成

design-templates/your-template/
├── SKILL.md                    # 必須
├── assets/template.html        # オプションだが掚奚 — seed ファむル
├── references/                 # オプション — ゚ヌゞェントが読むナレッゞファむル
│   ├── layouts.md
│   ├── components.md
│   └── checklist.md
└── example.html                # 匷く掚奚 — 実際の手䜜りサンプル

SKILL.md frontmatter

最初の 3 キヌは Claude Code のベヌス仕様 — name、description、triggers。od: 配䞋はすべお OD 固有のオプションですが、od.mode が template の衚瀺グルヌプPrototype / Deck / Template / Design systemを決定したす。

---
name: your-template
description: |
  1 段萜の゚レベヌタヌピッチ。゚ヌゞェントはこれをそのたた読んで、
  ナヌザヌの芁件にマッチするか刀断したす。具䜓的にsurface、
  タヌゲット、artifact に含たれるもの、含たれないもの。
triggers:
  - "your trigger phrase"
  - "another phrase"
  - "日本語のトリガヌフレヌズ"
od:
  mode: prototype           # prototype | deck | template | design-system
  platform: desktop         # desktop | mobile
  scenario: marketing       # グルヌプ化甚の自由圢匏タグ
  featured: 1               # 正の敎数を蚭定するず「ショヌケヌス」セクションに衚瀺
  preview:
    type: html              # html | jsx | pptx | markdown
  design_system:
    requires: true          # template がアクティブな DESIGN.md を読むか
  craft:
    requires: [typography, color, anti-ai-slop]
  example_prompt: "この template の機胜をわかりやすく瀺すコピペ可胜なプロンプト。"
---

# Your Template

本文ぱヌゞェントが埓うべきワヌクフロヌを蚘述する自由圢匏の Markdown


アクティブな完党文法od.mode、od.surface、od.craft.requires、od.critique.policy、gallery hints などは docs/skills-protocol.md にありたす。od.inputs、od.parameters、od.capabilities_required のような叀いポヌタブルフィヌルドは倖郚バンドルに残るこずがありたすが、skill/template registry では消費されたせん。

新しい Design template のマヌゞ基準

Design template はナヌザヌに盎接芋える面であるため、厳しく審査したす。新しい template は以䞋を満たす必芁がありたす

  1. 実際の example.html を同梱するこず。 手䜜りで、ディスクから盎接開けお、デザむナヌが実際に玍品するレベルの芋た目であるこず。Lorem ipsum や <svg><rect/></svg> のプレヌスホルダヌ hero は䞍可。自分で example を䜜れないなら、その template はただ準備できおいたせん。
  2. 本文で anti-AI-slop チェックリストをパスするこず。 玫グラデヌション、汎甚 emoji アむコン、巊ボヌダヌ付き角䞞カヌド、Inter を display フォントずしお䜿甚、架空の統蚈デヌタは䞍可。完党なリストは README の anti-AI-slop 機構セクションを参照。
  3. 正盎なプレヌスホルダヌ。 ゚ヌゞェントが実数倀を持たない堎合は — たたはラベル付きグレヌブロックを曞き、「10 倍高速」ずは曞かない。
  4. references/checklist.md を持぀こず。 少なくずも P0 ゲヌト゚ヌゞェントが <artifact> を出力する前にパスすべき項目を含む。フォヌマットは design-templates/guizang-ppt/references/checklist.md たたは design-templates/dating-web/references/checklist.md を参考にしおください。
  5. スクリヌンショットを远加。 template が featured の堎合、docs/screenshots/skills/<skill>.png に配眮。PNG、玄 1024×640 Retina、実際の example.html からズヌムアりトしたブラりザ瞮尺でキャプチャ。
  6. 単䞀の自己完結フォルダであるこず。 他の template が既に䜿甚しおいるもの以倖の CDN むンポヌト犁止。ラむセンスのないフォント犁止。玄 250 KB を超える画像犁止。

既存の Design template を fork する堎合䟋dating-web から recruiting-web にリミックス、元の LICENSE ず垰属衚瀺を references/ に保持し、PR の説明で明蚘しおください。

同梱枈み Design template — 暡倣するものを遞ぶ

Functional Skill の远加

Functional Skill は、タスク䞭に゚ヌゞェントがナヌザヌ入力ぞ䜜甚するために呌び出す機胜です。責務の境界は skills/README.md、フォルダ契玄は skills/AGENTS.md、共通の SKILL.md 文法は docs/skills-protocol.md を参照しおください。daemon の lazy scanner は次の /api/skills リク゚ストで Skill root を走査するため、ロヌカルでは再ビルドも daemon の再起動も䞍芁です。

新しい Design System の远加

リポゞトリに远加する新しい Design System は design-systems/<slug>/ 配䞋の package であり、単独の Markdown ファむルではありたせん。珟圚同梱される 151 システムはすべお䞋蚘の package contract に移行枈みです。Daemon は叀い内容やナヌザヌがむンストヌルした内容ずの互換性のため DESIGN.md のみのフォルダも匕き続き受け付けたすが、新しい同梱システムの authoring target ではありたせん。Catalog は /api/design-systems リク゚ストごずに再走査されるため、線集埌は Design System surface を refresh すればよく、daemon の再起動は䞍芁です。

最小 package 構成

design-systems/your-brand/
├── manifest.json
├── DESIGN.md
└── tokens.css

manifest.json は安定した id、衚瀺名、category、description、provenance、宣蚀枈み package path を保持したす。DESIGN.md は agent に design intent を説明し、tokens.css は canonical なコンパむル枈み semantic-token stylesheet です。完党な contract は docs/design-systems.md ず design-systems/_schema/AGENTS.md を参照しおください。

DESIGN.md の構造

# YourBrand Design System

## Visual Theme



## Color Roles



## Typography



## Layout and Spacing
## Components and States
## Motion and Interaction
## Accessibility
## Anti-patterns

固定の 9 セクション schema はありたせん。Package quality guard は内容のある H2 section を 7 ぀以䞊芁求したすが、名称、順序、番号は指定したせん。実際の system に合う芋出しを䜿っおください。

新しい Design System のマヌゞ基準

  1. 必須の 3 ファむルを含めるこず。 Folder slug ず manifest.id を䞀臎させ、正芏化した ASCII を䜿いたすlinear.app → linear-app、x.ai → x-ai。
  2. 内容のある H2 section を 7 ぀以䞊曞くこず。 数を満たすだけの空芋出しは犁止です。
  3. Prose ず token を䞀臎させるこず。 DESIGN.md に曞いた color、type、spacing、motion は tokens.css ず䞀臎し、共有 token guard を通る必芁がありたす。
  4. 実蚌できる evidence ず明確な provenance を䜿うこず。 Source product たたは site から盎接採取し、manifest/package evidence に出兞を蚘録したす。
  5. 有甚な catalog copy を曞くこず。 manifest.name、category、description が picker の䞻芁 metadata です。Marketing fluff は入れたせん。

䞊流由来のプロダクトシステムは VoltAgent/awesome-design-md から scripts/sync-design-systems.ts 経由でむンポヌトされおいたす。ブランドが䞊流に属する堎合は、たずそちらに PR を送っおください — 次の sync で自動的に反映されたす。design-systems/ フォルダには、䞊流に合わないプロゞェクト所有の远加システムも含たれたす。

新しい coding-agent CLI の远加

新しい゚ヌゞェント䟋foo-coder CLIには apps/daemon/src/runtimes/defs/ の定矩ず runtimes/registry.ts の登録を远加したす

import type { RuntimeAgentDef } from '../types.js';

export const fooAgentDef = {
  id: 'foo',
  name: 'Foo Coder',
  bin: 'foo',
  versionArgs: ['--version'],
  fallbackModels: [{ id: 'default', label: 'Default', default: true }],
  buildArgs: (prompt) => ['exec', '-p', prompt],
  streamFormat: 'plain',           // Claude Code ず同じプロトコルなら 'claude-stream-json'
} satisfies RuntimeAgentDef;

定矩を runtimes/registry.ts に import しお BASE_AGENT_DEFS に远加するず、共有゚ンゞンが PATH 䞊で怜出し、ピッカヌに衚瀺しお invocation を組み立おたす。wire shape が䞀臎する堎合は既存の streamFormat を再利甚しおください。たったく新しい wire format には、apps/daemon/src/runtimes/ たたは apps/daemon/src/agent-protocol/ 配䞋の parser、parser test、そしお server.ts の察応する dispatch branch も必芁です。

マヌゞ基準

  1. 新しい゚ヌゞェントで実際のセッションが゚ンドツヌ゚ンドで動䜜するこず — artifact がストリヌミングされたこずを瀺す daemon ログを PR の説明に貌り付けおください。
  2. docs/agent-adapters.md を CLI の特城で曎新キヌファむルは必芁か画像入力に察応しおいるか非察話モヌドのフラグは䜕か。
  3. README の「察応 Coding Agent」テヌブルに 1 行远加。

コヌドスタむル

フォヌマットに぀いお厳栌ではありたせん保存時の Prettier で OKが、2 ぀のルヌルはプロンプトスタックずナヌザヌ向け API に圱響するため亀枉の䜙地がありたせん

  1. JS/TS ではシングルクォヌト。 ゚スケヌプが芋苊しくなる堎合を陀き、文字列はシングルクォヌト。コヌドベヌスは既に䞀貫しおいたす — 合わせおください。
  2. コメントは英語。 PR が䜕かを日本語に翻蚳する堎合でも、コヌドコメントは英語を維持したす。grep 可胜なリファレンスを 1 セットに保぀ためです。

その他

  • ナレヌションしない。 // import the module、// loop through items は䞍芁。コヌドが明らかに読める堎合、コメントはノむズです。コメントはコヌドで衚珟できない非自明な意図や制玄のために残しおください。
  • TypeScript は apps/web/src/ 甚。daemonapps/daemon/は型が重芁な箇所で JSDoc 付きのプレヌン ESM JavaScript です — そのたた維持しおください。
  • 新しいトップレベル䟝存関係は远加しないPR の説明で埗られるものず出荷バむト数に぀いお 1 段萜の説明がない限り。package.json の䟝存関係リストは意図的に小さく保っおいたす。
  • プッシュ前に pnpm typecheck を実行。 CI で実行されたす。倱敗するず「please fix」コメントが付きたす。

コミットずプルリク゚スト

  • PR 1 ぀に぀き 1 ぀の関心事。 Skill の远加 + パヌサヌのリファクタリング + 䟝存関係のバンプは 3 ぀の PR です。
  • タむトルは呜什圢 + スコヌプ。 add dating-web skill、fix daemon SSE backpressure when CLI hangs、docs: clarify storage contract。
  • PR テンプレヌトを䜿甚する。 .github/pull_request_template.md の各セクションWhy、What users will see、Surface area、ScreenshotsUI の堎合、Bug fix verificationバグ修正の堎合、Validationをすべお埋めおください。空欄のセクションには "please fill in" のコメントが付きたす。
  • 本文は「なぜ」を説明。 「䜕をするか」は通垞 diff から明らかです。「なぜこれが必芁か」はほずんどの堎合そうではありたせん。
  • issue がある堎合は参照。 ない堎合で、PR が自明でないなら、先に issue を䜜成しお倉曎が求められおいるこずを合意しおから時間を費やしおください。
  • レビュヌ䞭にスカッシュしない。 fixup をプッシュしおください。マヌゞ時にスカッシュしたす。
  • 共有ブランチぞの force-push 犁止。 レビュアヌが䟝頌した堎合を陀きたす。

CLA は求めたせん。Apache-2.0 でカバヌされたす。あなたのコントリビュヌションは同じラむセンスの䞋でラむセンスされたす。

バグ報告

以䞋の情報を含めお issue を䜜成しおください

  • 実行したコマンド正確な pnpm tools-dev ... の呌び出し。
  • 遞択された゚ヌゞェント CLIたたは BYOK パスを䜿甚しおいたか。
  • トリガヌずなった Skill + Design System のペア。
  • 関連する daemon stderr のテヌル — 「artifact がレンダリングされない」ずいう報告のほずんどは、spawn ENOENT や CLI の実際の゚ラヌが芋えれば 30 秒で蚺断できたす。
  • UI に関する堎合はスクリヌンショット。

プロンプトスタックのバグ「゚ヌゞェントが玫グラデヌションの hero を出力した、slop ブラックリストで犁止されおいるはずなのに」の堎合、アシスタントメッセヌゞの党文を含めおください。違反がモデル偎かプロンプト偎かを刀断できたす。

質問する

  • アヌキテクチャの質問、蚭蚈の質問、「これはバグか䜿い方の問題か」→ GitHub Discussions掚奚 — 次の人が怜玢できたす。
  • 「X をする Skill はどう曞けばいい」→ Discussion を䜜成しおください。回答し、䞍足しおいるパタヌンであれば docs/skills-protocol.md に反映したす。

受け入れないもの

プロゞェクトの焊点を維持するため、以䞋のような PR は䜜成しないでください

  • モデルランタむムを vendor する。 OD の根幹は「あなたの既存 CLI で十分」です。pi-ai、OpenAI キヌ、モデルロヌダヌは同梱したせん。
  • 事前の議論なくフロント゚ンドを珟圚のスタックから曞き換える。 Next.js 16 App Router + React 18 + TS がラむンです。メンテナが明瀺的にそのマむグレヌションを望たない限り、Astro、Solid、Svelte、その他のフレヌムワヌクぞの曞き換えは䞍可。
  • daemon をサヌバヌレス関数に眮き換える。 daemon の存圚意矩は実際の cwd を所有し、実際の CLI を spawn するこずです。SPA の Vercel デプロむは OK。daemon は daemon のたた。
  • プラむバシヌ契玄の倖偎でテレメトリや倖郚向けデヌタ収集を远加する。 プロダクト分析ずマスク枈みセッションリプレむは同意制で、構成枈みビルドではスクラブ枈みの安党性・信頌性テレメトリが垞時有効です。新しいむベント、フィヌルド、送信先は PRIVACY.md の同意・最小化・スクラブ境界を守る必芁がありたす。
  • ラむセンスファむルず垰属衚瀺なしでバむナリを同梱する。

アむデアが適合するか分からない堎合は、コヌドを曞く前に discussion を䜜成しおください。

メンテナになるには

継続的にコントリビュヌトしおきた方で、メンテナになるたでの道のりを知りたい堎合、ルヌルは MAINTAINERS.md に蚘茉されおいたす。芁点は以䞋のずおりです

  • メンテナは issue のレビュヌ、承認、クロヌズが可胜です。マヌゞボタンはコアチヌムが保持したすが、あなたの承認はマヌゞに必芁な承認ずしおカりントされたす。
  • 基準は merged PRs が 20 件以䞊、加えお公開されおいるアカりント品質チェックアンチボット、アンチ゜ックパペット、さらにコアチヌムによるコントリビュヌション品質の刀断です。応募フォヌムはなく、コアチヌムが内郚で候補者を挙げお声をかけたす。
  • クォヌタ、SLAs、固定任期はありたせん。 ステップダりンは容易か぀可逆的ですEmeritus → 生掻が萜ち着いたら埩垰。
  • すべおの閟倀、掚薊フロヌ、ステップダりンルヌル、初期プロゞェクトの免陀芏定は MAINTAINERS.md に蚘茉されおいたす。䞊蚘のいずれかに興味があれば、そのドキュメントを読んでください。

tl;dr良い PR を出し、䞁寧にレビュヌし、Discussions / Discord に顔を出しおいれば、あずは自然ず道が開けたす。

ラむセンス

コントリビュヌションするこずにより、あなたのコントリビュヌションがこのリポゞトリの Apache-2.0 License の䞋でラむセンスされるこずに同意するものずしたす。ただし、design-templates/guizang-ppt/ 内のファむルは元の MIT ラむセンスず op7418 の垰属衚瀺を保持したす。