Knowledge OS Design Principles v1.0.0 — Phase 5 AI Development Rules

Introduction

AIを使っても、製品の判断はAIに任せない

AI開発支援ツールは、コードや文章を短時間で作成できます。一方で、指示が曖昧なまま実装を任せると、 AIごとに異なるデザイン、名称、フォルダ構成、コンポーネントが作られます。

その結果、機能は動いていても、 Knowledge OS全体の統一感が失われ、利用者が画面ごとに操作を覚え直す製品になります。

AIは実装担当者であり、製品方針の決定者ではありません。 UI、文章、情報構造、命名、技術構成は、 Knowledge OS Design Principlesに従います。

この章の対象

Cursor

画面実装、既存機能の改修、UIコンポーネントの構築を担当します。

Claude

利用者向け文章、説明文、ヘルプ、エラー文の作成を担当します。

Codex

コード構造、命名、リファクタリング、保守性の改善を担当します。

1 AI共通ルール

Cursor、Claude、Codexのいずれを使用する場合も、次のルールを共通の最上位ルールとします。

参照順位

既存機能とデータを壊さないこと
Knowledge OS Design Principles
既存の共通コンポーネント
対象機能の設計書・仕様書
AI自身の一般的な推奨

AIの一般論よりKnowledge OSのルールを優先する AIが一般的なUIや構成を推奨しても、 Knowledge OS Design Principlesと異なる場合は採用しません。

共通必須事項

既存実装を調査してから変更する
変更対象と影響範囲を整理する
既存の共通部品を再利用する
一般利用者向け表示は日本語にする
技術用語を利用者向け画面に露出させない
Loading、Empty、Errorの状態を実装する
ビルドと主要操作を確認する
変更内容を報告書へ残す

共通禁止事項

指示されていない機能を勝手に追加する
既存機能を説明なく削除する
画面ごとに新しいデザインルールを作る
同じ役割のコンポーネントを重複作成する
その場しのぎのCSSを各画面へ追加する
利用者向け画面へ英語を表示する
既存データの移行を考慮せずスキーマを変更する
ビルド未確認の状態で完了と報告する

英語禁止の範囲

英語禁止は、利用者が目にする画面上の文言を対象とします。ソースコード上のコンポーネント名、変数名、型名は、一般的な英語命名を使用します。

対象	ルール
画面タイトル	日本語
ボタン・メニュー	日本語
エラー・案内	日本語
コード上の名称	英語のPascalCase、camelCaseを使用
技術ログ	必要に応じて英語可

02 — Cursor Rules

2 Cursor Rules

Cursorの役割は、画面を新しくデザインすることではなく、定義済みのデザインを正確に実装することです。

Cursorが最初に行うこと

1

既存コードを確認する 対象画面、関連コンポーネント、状態管理、API呼び出しを確認します。

2

既存機能を一覧化する 現在利用できる機能と、変更後も維持する機能を整理します。

3

Design Principlesを参照する Phase 3のUIルールとPhase 4の対象画面ルールを確認します。

4

変更計画を作る 変更ファイル、再利用部品、新規部品、影響範囲を整理します。

5

実装後に検証する ビルド、主要操作、Empty、Loading、Errorを確認します。

Cursor必須ルール

画面の主要領域はカードUIで整理する
標準のカード内余白は24pxにする
主要な操作や状態にはアイコンを付ける
アイコンライブラリはLucide Iconsに統一する
画面上の文言は日本語にする
専門用語を一般的な言葉へ置き換える
既存のDesign Tokenを使用する
共通コンポーネントを優先して使用する

Cursor禁止ルール

Bootstrap Tableを使用する
Bootstrap依存の密集した管理画面UIを新規作成する
画面ごとに独自の色や余白を定義する
絵文字を正式なUIアイコンとして使用する
Lucide以外のアイコンライブラリを混在させる
英語のボタンや見出しを表示する
OCR、RAG、Embeddingなどをそのまま画面表示する
既存部品を確認せず新規コンポーネントを作成する
インラインスタイルを大量に追加する

03 — Cursor UI Rules

3 Cursor UI実装ルール

Bootstrap Tableは禁止

Knowledge OSでは、Bootstrap Tableプラグインや、 Bootstrap風の列数が多い高密度な管理テーブルを新規画面へ使用しません。

資料、検索結果、設定項目などは、内容を理解しやすいカードUIまたは専用リストで表示します。

使用する

DocumentCard
SearchResultCard
SettingCard
StatusCard
ActionCard

使用しない

Bootstrap Table
文字が密集した多列テーブル
各行に多数の操作ボタンがある表
スマートフォンで読めない固定幅表

単純な比較表は例外設定値や少数項目の比較など、行と列の関係が重要な場合は、 HTMLのセマンティックなtable要素を使用できます。ただし、Bootstrap Tableプラグインは使用しません。

カードUI

項目	標準
内側余白	24px
カード間隔	16pxまたは24px
角丸	12px
境界線	1px / Neutral 200
背景	白
影	原則なし

余白

カード内余白：24px
フォーム項目間：24px
セクション間：32〜48px
ラベルと入力欄：8px
アイコンと文字：8px

余白を埋めるために装飾を追加してはいけません。情報量が少ない画面には、適切な空白を残します。

アイコン

Lucide Iconsのみを使用する
標準サイズは20pxまたは24pxとする
ボタン内では18〜20pxを使用する
アイコンには文字ラベルを併記する
状態表示ではアイコン・色・文章を組み合わせる

推奨Lucide Icons

用途	Lucide Icon
資料	`FileText`
フォルダ	`Folder`
検索	`Search`
追加	`Plus`
編集	`Pencil`
削除	`Trash2`
設定	`Settings`
AIに聞く	`MessageCircleQuestion`
成功	`CircleCheck`
警告	`TriangleAlert`
エラー	`CircleAlert`
読み込み中	`LoaderCircle`

既存アイコンの段階移行 Lucide Iconsを標準アイコンライブラリとします。 Bootstrap Iconsなどの既存アイコンは、既存機能を壊さないため直ちに全面置換しません。新規利用は禁止し、対象画面の改修時にLucide Iconsへ段階的に移行します。代替の目安：bi-robot → Bot / MessageCircleQuestion、AI処理 → Sparkles、ローカルAI → Cpu。

04 — Cursor Content Rules

4 Cursorの文言・状態ルール

英語を画面に出さない

推奨

資料を追加
検索しています…
設定を保存しました
接続を確認
該当する資料がありません

禁止

Add Document
Loading...
Settings Saved
Test Connection
No Data

専門用語を画面に出さない

技術用語	利用者向け表現
OCR	画像やPDFから文字を読み取る
Embedding	内容から検索できるように準備する
Indexing	検索できるように整理する
RAG	登録資料をもとに回答する
LLM	AI
Runtime	ローカルAIの実行環境
Provider	利用するAIサービス
API Key	APIキー。初出時に説明を付ける

必須状態

Cursorは、通常状態だけを実装して完了としてはいけません。

初回状態
Loading状態
Empty状態
成功状態
一部失敗状態
Error状態
接続できない状態

状態ごとの文言

状態	表示例
Loading	資料の内容を確認しています…
Empty	まだ資料が登録されていません
成功	「契約書.pdf」を登録しました
一部失敗	8件を登録し、2件は登録できませんでした
Error	資料を保存できませんでした。保存先を確認してください

Cursor完了報告

実装完了報告には、次を含めてください。

1. 変更した画面・機能
2. 変更したファイル
3. 再利用した共通コンポーネント
4. 新規作成したコンポーネント
5. 実装した画面状態
6. ビルド結果
7. 動作確認結果
8. 残っている課題
9. 既存機能への影響

05 — Claude Rules

5 Claude Rules

Claudeの役割は、正しい文章を書くことだけではなく、利用者が迷わず行動できる文章を書くことです。

対象文章

画面タイトル
ボタン名
操作説明
初回案内
Empty State
Loading文
成功・警告・エラー文
ヘルプ記事
ユーザーマニュアル
セットアップ案内

Claude必須ルール

やさしい日本語を使用する
高齢者が読んでも意味を理解できる文章にする
1文を短くする
結論または操作結果を先に書く
専門用語を避ける
専門用語が必要な場合は、その場で説明する
利用者が次に行う操作を具体的に書く
画面上の実際の名称と文章を一致させる

文章の基準

項目	基準
1文の長さ	40〜60文字程度を目安にする
1段落	3〜5行程度
漢字	一般的な漢字に限定する
カタカナ語	一般利用者が理解できるものだけ使用する
敬語	丁寧だが過剰にしない
主語	省略して意味が曖昧になる場合は書く

高齢者が読める文章

良い例

資料を登録できませんでした。保存先のフォルダを確認して、もう一度お試しください。

悪い例

ストレージへの書き込み処理でエラーが発生しました。ディレクトリの権限設定を確認してください。

専門用語の説明

良い例

APIキーとは、クラウドAIを利用するための認証情報です。契約しているAIサービスの画面で取得できます。

悪い例

ProviderのAPI Keyを設定してください。

Claude禁止ルール

製品を過度に宣伝する文章
AIを擬人化した過剰な表現
長い前置き
利用者を責めるエラー文
「不正です」「無効です」だけの説明
技術者にしか分からない略語
英語見出しと日本語説明の混在
画面に存在しない操作の案内

06 — Claude Text Patterns

6 Claude文章パターン

操作説明

「何をするか」「どこを押すか」「その後どうなるか」の順で書きます。

登録する資料を選びます。
画面中央の「ファイルを選ぶ」を押してください。
選んだ資料が一覧に表示されます。

成功文

成功した対象と、次にできることを書きます。

「相続手続きの進め方.pdf」を登録しました。
「資料を見る」から内容を確認できます。

エラー文

「問題」「影響」「解決方法」の順で書きます。

資料の文字を読み取れませんでした。
元の資料は保存されています。
画像が鮮明か確認して、もう一度お試しください。

Empty State

現在の状態と、最初の操作を書きます。

まだ資料が登録されていません。
PDF、Word、画像などを登録すると、
資料の内容を検索できるようになります。

［資料を追加］

Loading

システム内部の処理名ではなく、利用者の資料に対して何をしているかを書きます。

使用する

資料を読み込んでいます…
文字を読み取っています…
関連する資料を探しています…
回答をまとめています…

使用しない

Processing...
Embedding中…
RAG実行中…
LLM推論中…

ヘルプ記事

ヘルプ記事は次の構造に統一します。

この操作でできること
操作前に確認すること
番号付きの操作手順
操作後にどうなるか
うまくいかない場合

Claudeへの共通指示

Knowledge OSの利用者向け文章を作成してください。

必須条件：
- やさしい日本語を使う
- 高齢者でも理解できる文章にする
- 1文を短くする
- 結論や操作結果を先に書く
- 専門用語は避ける
- 専門用語が必要な場合は説明を付ける
- 英語の見出しやボタン名を使わない
- 利用者が次に何をすればよいかを書く
- 実際の画面名とボタン名に合わせる
- 利用者を責める表現を使わない

07 — Codex Rules

7 Codex Rules

Codexの役割は、コードを短くすることではなく、 Knowledge OSを安全に変更し続けられる構造にすることです。

Codexの主な担当

コンポーネント分割
共通処理の整理
型定義
サービス層の整理
フォルダ構成の改善
重複コードの解消
テスト追加
既存コードの安全なリファクタリング

Codex必須ルール

既存のアーキテクチャを確認してから変更する
UIと業務処理を分離する
画面コンポーネントへAPI処理を直接書きすぎない
型を明確に定義する
共通処理を適切なサービスへ分離する
既存のDesign Tokenと共通UIを維持する
変更範囲を必要最小限にする
段階的にリファクタリングする
ビルドとテストを実行する

デザインを壊さない

Codexがコード構造を改善する場合でも、 DOM構造、CSSクラス、表示順、文言、画面状態を意図なく変更してはいけません。

リファクタリング前後の画面構造を比較する。
共通化によって余白や色が変わらないことを確認する。
条件分岐の整理によってEmptyやErrorが消えないようにする。
コンポーネント分割後もキーボード操作を維持する。
既存のLucide Iconを別アイコンへ置き換えない。

Codex禁止ルール

全体を書き直す大規模変更
目的の異なる処理を1つのコンポーネントへ集約する
型をanyで回避する
例外を握りつぶす
エラー表示をconsoleだけで終わらせる
既存の画面文言を勝手に変更する
デザインルールを独自解釈で変更する
使用中の旧APIを確認せず削除する

Codexへの共通指示

既存のKnowledge OSを安全にリファクタリングしてください。

必須条件：
- 既存機能と画面表示を維持する
- 変更前に関連ファイルと依存関係を確認する
- UI、状態管理、サービス、型定義を適切に分離する
- 既存のコンポーネント命名規則を守る
- 既存のフォルダ構成を尊重する
- Design TokenとLucide Iconsを維持する
- 画面上の日本語文言を勝手に変更しない
- anyの追加を避ける
- エラー処理を維持または改善する
- 変更は必要最小限にする
- ビルドとテストを実行する

08 — Naming & Structure

8 命名とフォルダ構成

コンポーネント命名

Vue、ReactなどのUIコンポーネントは、役割が分かる英語のPascalCaseで命名します。

種類	形式	例
ページ	`機能名 + Page`	`DocumentsPage`
カード	`対象 + Card`	`DocumentCard`
一覧	`対象 + List`	`DocumentList`
入力	`対象 + Input`	`SearchInput`
ダイアログ	`目的 + Dialog`	`DeleteDocumentDialog`
状態	`状態 + State`	`DocumentEmptyState`
サービス	`対象 + Service`	`DocumentImportService`
型	対象を表す名詞	`DocumentMetadata`

使用しない名前

NewComponent
Common
Utils2
Temp
TestPage
DataManager
ComponentA
役割の分からない略語

イベントと関数

用途	例
クリック処理	`handleAddDocument`
データ取得	`fetchDocuments`
保存	`saveSettings`
状態判定	`isDocumentLoading`
表示可否	`canDeleteDocument`

推奨フォルダ構成

src/
├── components/
│   ├── common/
│   │   ├── AppButton.vue
│   │   ├── AppCard.vue
│   │   ├── AppDialog.vue
│   │   ├── AppEmptyState.vue
│   │   ├── AppLoadingState.vue
│   │   └── AppStatusMessage.vue
│   │
│   ├── documents/
│   │   ├── DocumentCard.vue
│   │   ├── DocumentList.vue
│   │   ├── DocumentViewer.vue
│   │   └── DocumentMetadataPanel.vue
│   │
│   ├── search/
│   │   ├── SearchInput.vue
│   │   ├── SearchFilterBar.vue
│   │   └── SearchResultCard.vue
│   │
│   └── ai/
│       ├── QuestionComposer.vue
│       ├── AnswerView.vue
│       └── SourceDocumentList.vue
│
├── pages/
│   ├── HomePage.vue
│   ├── DocumentsPage.vue
│   ├── DocumentDetailPage.vue
│   ├── DocumentImportPage.vue
│   ├── AskAiPage.vue
│   ├── SearchPage.vue
│   ├── SettingsPage.vue
│   └── HelpPage.vue
│
├── services/
│   ├── documentService.ts
│   ├── searchService.ts
│   ├── aiService.ts
│   └── settingsService.ts
│
├── stores/
│   ├── documentStore.ts
│   ├── searchStore.ts
│   └── settingsStore.ts
│
├── types/
│   ├── document.ts
│   ├── search.ts
│   ├── ai.ts
│   └── settings.ts
│
├── composables/
│   ├── useDocuments.ts
│   ├── useSearch.ts
│   └── useAiQuestion.ts
│
├── styles/
│   ├── tokens.css
│   ├── base.css
│   └── utilities.css
│
└── router/
    └── index.ts

フォルダ構成の注意

既存構成がある場合は、無理に全面移行しない。
新規機能から段階的に整理する。
画面固有部品と共通部品を分ける。
サービス層へUIコンポーネントを依存させない。
typesへ実行処理を書かない。
utilsへ業務ロジックを集めすぎない。

09 — AI Collaboration Workflow

9 AI協業フロー

1つのAIに、設計、文章、実装、リファクタリングをすべて同時に依頼しません。

推奨順序

1

仕様を決める 人間が目的、対象利用者、必要機能、禁止事項を決定します。

2

Claudeで文章を整理する 画面タイトル、説明、状態文、ヘルプ文を作成します。

3

Cursorで画面を実装する Phase 3・4・5に従い、既存機能を維持して実装します。

4

Codexで構造を確認する 重複、責務、型、保守性を確認し、必要な範囲だけ整理します。

5

人間が最終確認する 利用者目線、業務上の正しさ、既存機能への影響を確認します。

役割分担

作業	主担当	確認担当
画面目的の決定	人間	Cursor
画面文章	Claude	人間
UI実装	Cursor	人間
コード構造	Codex	Cursor・人間
業務上の正しさ	人間	AIは補助のみ
最終承認	人間	AIは行わない

AI間で引き継ぐ情報

画面の目的
対象利用者
主要操作
維持する既存機能
使用する共通コンポーネント
確定済みの画面文言
変更対象ファイル
既知の問題と制約
テスト結果

AI同士の推測による引き継ぎは禁止前工程の決定内容は、設計書、実装報告書、確定文言として明示的に引き継ぎます。

10 — Prompt Template

10 AI共通指示テンプレート

AIへKnowledge OSの開発を依頼する際は、次の共通指示をプロンプト冒頭へ含めます。

Knowledge OS Design Principles v1.0.0に従って作業してください。

参照する章：
- Phase 1：Product Philosophy
- Phase 2：UX Principles
- Phase 3：UI Design System
- Phase 4：Screen Guidelines
- Phase 5：AI Development Rules

最上位ルール：
1. 既存機能と既存データを壊さない
2. 指示されていない機能を勝手に追加しない
3. 既存の共通コンポーネントを優先して使用する
4. 一般利用者向け画面は日本語にする
5. 技術用語を画面へ直接表示しない
6. Bootstrap Tableを新規使用しない
7. 主要情報はカードUIで表示する
8. カード内余白は24pxを標準とする
9. アイコンはLucide Iconsのみを使用する
10. Loading、Empty、Errorを必ず実装する
11. AIより利用者の資料を主役にする
12. 作業後にビルドと主要操作を確認する

作業前に次を報告してください：
- 現在の実装状況
- 維持する既存機能
- 変更予定ファイル
- 再利用する共通コンポーネント
- 新規作成が必要な部品
- 想定される影響範囲

作業後に次を報告してください：
- 実装内容
- 変更ファイル
- ビルド結果
- テスト結果
- 未解決事項
- 既存機能への影響

Cursor追加指示

Cursor追加ルール：
- Phase 4の対象画面ガイドラインを確認する
- 独自デザインを追加しない
- カード、ボタン、ダイアログは既存部品を再利用する
- インラインCSSを増やさない
- 画面上の英語を日本語へ置き換える
- Lucide以外のアイコンを追加しない
- Bootstrap Tableを使用しない
- 通常状態だけで完了としない

Claude追加指示

Claude追加ルール：
- やさしい日本語で書く
- 高齢者でも読める文章にする
- 1文を短くする
- 結論や結果を先に書く
- 専門用語は避ける
- 必要な専門用語には説明を付ける
- 利用者が次に行う操作を書く
- 実際の画面名とボタン名に合わせる

Codex追加指示

Codex追加ルール：
- 既存のフォルダ構成と命名を確認する
- UI、状態管理、サービス、型を分離する
- anyを追加しない
- エラー処理を握りつぶさない
- 画面のDOM構造とデザインを意図なく変えない
- 日本語文言を勝手に変更しない
- 大規模な全面書き換えを避ける
- 段階的に変更する

11 — AI Output Review

11 AI生成物レビュー

AIが「完了」と報告しても、そのまま採用しません。次の項目を人間または別のAIが確認します。

Cursorレビュー

Bootstrap Tableが追加されていない。
主要情報がカードUIで整理されている。
カード内余白が24pxを基準としている。
Lucide Iconsだけを使用している。
画面上に英語が残っていない。
専門用語が一般向け表現になっている。
Phase 4の画面構造に従っている。
Loading、Empty、Errorがある。
既存機能が維持されている。

Claudeレビュー

高齢者でも意味を理解できる。
1文が長すぎない。
重要な内容が文章の前半にある。
専門用語に説明がある。
利用者を責める表現がない。
次の操作が具体的に書かれている。
実際の画面名称と一致している。
英語見出しがない。

Codexレビュー

コンポーネント名から役割が分かる。
フォルダ構成が既存設計と一致している。
UIと業務処理が適切に分離されている。
anyが不用意に追加されていない。
例外処理が維持されている。
重複コードが増えていない。
デザインと文言が変わっていない。
ビルドとテストが成功している。

不合格条件

ビルドしていない
既存機能の確認をしていない
画面状態を通常時しか実装していない
英語や技術用語が利用者画面に残っている
既存共通部品と同じ部品を新しく作っている
大規模な変更を一度に行っている
残課題を報告せず完了としている

AI生成物の品質は、コード量や作業速度では判断しません。 Knowledge OSらしさ、利用者の分かりやすさ、既存機能の安全性、今後の変更しやすさで判断します。

12 — Definition of Done

AI開発タスクの完成条件

設計

対象画面・機能の目的が明確である。
Design Principlesの参照箇所が明確である。
変更範囲と影響範囲が整理されている。
既存機能の維持方針が明確である。

UI

カードUIを基本としている。
標準余白が統一されている。
Lucide Iconsに統一されている。
英語・専門用語が利用者画面にない。
Phase 3・4に準拠している。

文章

やさしい日本語である。
高齢者が読める。
操作結果と次の操作が分かる。
エラーに解決方法がある。

コード

コンポーネント名と責務が明確である。
既存フォルダ構成と整合している。
型が適切に定義されている。
エラー処理がある。
重複コードが増えていない。

検証

ビルドが成功している。
主要操作を確認している。
Loading、Empty、Errorを確認している。
既存機能への影響を確認している。
残課題が報告されている。

完成の定義 AIがコードや文章を出力した時点では完成ではありません。 Knowledge OSのルールに沿っていることを確認し、ビルド・操作・状態・文言の検証が完了した時点で完成とします。

Closing

AIを増やしても、製品の人格は一つにする

Cursor、Claude、Codexは、それぞれ異なる能力と出力傾向を持っています。

しかし、利用者から見えるKnowledge OSは一つの製品です。どのAIが作った画面、文章、コードであっても、同じ考え方、同じ言葉、同じ操作方法で動かなければなりません。

Cursorは、決められた画面を実装する。
Claudeは、利用者が理解できる文章を書く。
Codexは、壊れにくいコード構造をつくる。
最終判断は、人間が行う。

最終原則

AIは製品方針を勝手に変更しない。
既存機能を壊さない。
利用者向け画面では、やさしい日本語を使う。
カードUIと24pxの余白を基本とする。
アイコンはLucide Iconsに統一する。
Bootstrap Tableは使用しない。
専門用語は利用者の言葉へ置き換える。
デザインより利用者の理解を優先する。
速さより一貫性と安全性を優先する。
AIの出力は必ず人間が確認する。

Phase 5 AI Development Rules

AIを使っても、製品の判断はAIに任せない

この章の対象

目次

1 AI共通ルール

参照順位

共通必須事項

共通禁止事項

英語禁止の範囲

2 Cursor Rules

Cursorが最初に行うこと

Cursor必須ルール

Cursor禁止ルール

3 Cursor UI実装ルール

Bootstrap Tableは禁止

使用する

使用しない

カードUI

余白

アイコン

推奨Lucide Icons

4 Cursorの文言・状態ルール

英語を画面に出さない

推奨

禁止

専門用語を画面に出さない

必須状態

状態ごとの文言

Cursor完了報告

5 Claude Rules

対象文章

Claude必須ルール

文章の基準

高齢者が読める文章

良い例

悪い例

専門用語の説明

良い例

悪い例

Claude禁止ルール

6 Claude文章パターン

操作説明

成功文

エラー文

Empty State

Loading

使用する

使用しない

ヘルプ記事

Claudeへの共通指示

7 Codex Rules

Codexの主な担当

Codex必須ルール

デザインを壊さない

Codex禁止ルール

Codexへの共通指示

8 命名とフォルダ構成

コンポーネント命名

使用しない名前

イベントと関数

推奨フォルダ構成

フォルダ構成の注意

9 AI協業フロー

推奨順序

役割分担

AI間で引き継ぐ情報

10 AI共通指示テンプレート

Cursor追加指示

Claude追加指示

Codex追加指示

11 AI生成物レビュー

Cursorレビュー

Claudeレビュー

Codexレビュー

不合格条件

AI開発タスクの完成条件

設計

UI

文章

コード

Phase 5
AI Development Rules