claudeos-core 1.3.0 → 1.4.0

package/README.hi.md

@@ -1,6 +1,6 @@
 # ClaudeOS-Core
 
-**एक कमांड। आपका पूरा Claude Code डॉक्यूमेंटेशन — आपके वास्तविक सोर्स कोड से ऑटो-जेनरेट।**
+**एकमात्र टूल जो पहले आपका सोर्स कोड पढ़ता है, deterministic एनालिसिस से स्टैक और पैटर्न कन्फर्म करता है, फिर आपके प्रोजेक्ट के लिए सटीक Claude Code रूल्स जेनरेट करता है।**
 
 ```bash
 npx claudeos-core init
@@ -12,20 +12,50 @@ ClaudeOS-Core आपका कोडबेस पढ़ता है, हर प
 
 ---
 
-## समस्या
+## ClaudeOS-Core क्यों?
 
-Claude Code शक्तिशाली है, लेकिन यह _आपके_ प्रोजेक्ट की कन्वेंशन्स को नहीं जानता। मैन्युअली `CLAUDE.md`, दर्जनों rules और scaffolding skills लिखने में घंटों लगते हैं — और कोडबेस बदलते ही ये पुराने हो जाते हैं।
+> इंसान प्रोजेक्ट का वर्णन करता है → LLM डॉक्यूमेंटेशन जेनरेट करता है
 
-## समाधान
+ClaudeOS-Core:
 
-ClaudeOS-Core पूरी प्रक्रिया को ऑटोमेट करता है:
+> कोड सोर्स का विश्लेषण करता है → कोड कस्टम प्रॉम्प्ट बनाता है → LLM डॉक्यूमेंटेशन जेनरेट करता है → कोड आउटपुट को वेरिफाई करता है
 
-1. **स्कैन** — स्टैक, डोमेन, ORM, डेटाबेस, पैकेज मैनेजर ऑटो-डिटेक्ट
-2. **गहन विश्लेषण** — कंट्रोलर पैटर्न, सर्विस लेयर्स, नेमिंग कन्वेंशन, एरर हैंडलिंग, सिक्योरिटी, टेस्टिंग और 50+ कैटेगरी
-3. **जेनरेट** — `CLAUDE.md`, Standards (15–19 फाइलें), Rules, Skills, Guides (9 फाइलें), Master Plans, DB डॉक्स और MCP गाइड का पूरा डॉक्यूमेंटेशन इकोसिस्टम
-4. **वैलिडेट** — 5 बिल्ट-इन वेरिफिकेशन टूल्स कंसिस्टेंसी सुनिश्चित करते हैं
+### मूल समस्या: LLM अनुमान लगाता है। कोड कन्फर्म करता है।
 
-कुल समय: प्रोजेक्ट साइज़ के अनुसार **5–18 मिनट**। शून्य मैन्युअल कॉन्फ़िगरेशन।
+जब आप Claude से "इस प्रोजेक्ट का विश्लेषण करो" कहते हैं, तो यह स्टैक, ORM, डोमेन स्ट्रक्चर का **अनुमान** लगाता है।
+
+**ClaudeOS-Core अनुमान नहीं लगाता।** Claude Node.js:
+
+- `build.gradle` / `package.json` / `pyproject.toml` → **confirmed**
+- directory scan → **confirmed**
+- Java 5 patterns, Kotlin CQRS/BFF, Next.js App Router/FSD → **classified**
+- domain groups → **split**
+- stack-specific prompt → **assembled**
+
+### परिणाम
+
+अन्य टूल "सामान्य रूप से अच्छा" डॉक्यूमेंटेशन बनाते हैं।
+ClaudeOS-Core ऐसा डॉक्यूमेंटेशन बनाता है जो जानता है कि प्रोजेक्ट `ApiResponse.ok()` इस्तेमाल करता है — क्योंकि इसने वास्तविक कोड पढ़ा है।
+
+### Before & After
+
+**ClaudeOS-Core के बिना**:
+```
+❌ JPA repository (MyBatis)
+❌ ResponseEntity.success() (ApiResponse.ok())
+❌ order/controller/ (controller/order/)
+→ 20 min fix per file
+```
+
+**ClaudeOS-Core के साथ**:
+```
+✅ MyBatis mapper + XML (build.gradle)
+✅ ApiResponse.ok() (source code)
+✅ controller/order/ (Pattern A)
+→ immediate match
+```
+
+यह अंतर संचयी है। प्रतिदिन 10 कार्य × 20 मिनट बचत = **प्रतिदिन 3+ घंटे**।
 
 ---
 
@@ -79,6 +109,7 @@ Gradle मल्टी-मॉड्यूल संरचना वाले Kot
 - **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
 - **RSC/Client split**: `client.tsx` पैटर्न डिटेक्ट, Server/Client कम्पोनेंट सेपरेशन ट्रैक
 - **Config fallback**: `package.json` में न होने पर भी config फ़ाइलों से Next.js/Vite/Nuxt डिटेक्ट (monorepo सपोर्ट)
+- **Deep directory fallback**: React/CRA/Vite/Vue/RN प्रोजेक्ट्स के लिए किसी भी गहराई पर `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/` स्कैन
 
 ---
 
@@ -117,7 +148,7 @@ bash claudeos-core-tools/bootstrap.sh
 
 ### आउटपुट भाषा (10 भाषाएँ)
 
-`--lang` के बिना `init` चलाने पर, एरो कीज़ से भाषा चुनने का इंटरैक्टिव सेलेक्टर दिखाई देगा:
+`--lang` के बिना `init` चलाने पर, एरो कीज़ या नंबर कीज़ से भाषा चुनने का इंटरैक्टिव सेलेक्टर दिखाई देगा:
 
 ```
 ╔══════════════════════════════════════════════════╗
@@ -132,10 +163,10 @@ bash claudeos-core-tools/bootstrap.sh
   ❯  7. hi     — हिन्दी (Hindi)
      ...
 
-  ↑↓ Move  ↵ Select
+  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
 ```
 
-एरो से मूव करने पर विवरण उस भाषा में बदलता है। सेलेक्टर स्किप करने के लिए:
+सेलेक्शन मूव करने पर विवरण उस भाषा में बदलता है। सेलेक्टर स्किप करने के लिए:
 
 ```bash
 npx claudeos-core init --lang hi    # हिन्दी
@@ -387,16 +418,21 @@ ClaudeOS-Core द्वारा जेनरेट किए गए डॉक
 | फाइल | कब | गारंटी |
 |---|---|---|
 | `CLAUDE.md` | हर कन्वर्सेशन शुरू होने पर | हमेशा |
-| `.claude/rules/*.md` | फाइल एडिट करते समय (`paths: ["**/*"]`) | हमेशा |
-| `.claude/rules/00.core/00.standard-reference.md` | ↑ ऊपर में शामिल | हमेशा |
+| `.claude/rules/00.core/*` | फाइल एडिट करते समय (`paths: ["**/*"]`) | हमेशा |
+| `.claude/rules/10.backend/*` | फाइल एडिट करते समय (`paths: ["**/*"]`) | हमेशा |
+| `.claude/rules/30.security-db/*` | फाइल एडिट करते समय (`paths: ["**/*"]`) | हमेशा |
+| `.claude/rules/40.infra/*` | केवल config/infra फाइल एडिट करते समय (स्कोप्ड paths) | सशर्त |
+| `.claude/rules/50.sync/*` | केवल claudeos-core फाइल एडिट करते समय (स्कोप्ड paths) | सशर्त |
 
-### standard-reference रूल के ज़रिए पढ़ी जाने वाली फाइलें
+### रूल रेफरेंस के ज़रिए ऑन-डिमांड पढ़ी जाने वाली फाइलें
 
-`00.standard-reference.md` रूल Claude Code को कोड लिखने से पहले ये डॉक्यूमेंट Read करने का निर्देश देता है:
+हर रूल फाइल `## Reference` सेक्शन में संबंधित standard को लिंक करती है। Claude केवल वर्तमान कार्य से संबंधित standard पढ़ता है:
 
 - `claudeos-core/standard/**` — कोडिंग पैटर्न, ✅/❌ उदाहरण, नेमिंग कन्वेंशन
 - `claudeos-core/database/**` — DB स्कीमा (क्वेरी, मैपर, माइग्रेशन के लिए)
 
+`00.standard-reference.md` बिना संबंधित रूल वाले standard की खोज के लिए एक डायरेक्टरी के रूप में कार्य करता है।
+
 ### न पढ़ी जाने वाली फाइलें (कॉन्टेक्स्ट बचत)
 
 standard-reference रूल के `DO NOT Read` सेक्शन द्वारा स्पष्ट रूप से बाहर:
@@ -450,19 +486,31 @@ npx claudeos-core restore
 
 ## क्या अलग है?
 
-| | ClaudeOS-Core | SuperClaude | मैन्युअल CLAUDE.md | जेनेरिक Skills |
-|---|---|---|---|---|
-| **कोड पढ़ता है** | ✅ गहन विश्लेषण (55–95 कैटेगरी) | ❌ बिहेवियर इंजेक्शन | ❌ मैन्युअल राइटिंग | ❌ प्री-बिल्ट टेम्पलेट |
-| **प्रोजेक्ट-स्पेसिफिक आउटपुट** | ✅ हर फाइल आपके पैटर्न रिफ्लेक्ट करती है | ❌ जेनेरिक कमांड | आंशिक | ❌ वन-साइज़-फिट्स-ऑल |
-| **मल्टी-स्टैक** | ✅ ऑटो-डिटेक्ट + अलग विश्लेषण | ❌ स्टैक-एग्नॉस्टिक | मैन्युअल | अनिश्चित |
-| **Kotlin + CQRS/BFF** | ✅ मल्टी-मॉड्यूल, Command/Query विभाजन | ❌ | ❌ | ❌ |
-| **बहुभाषी** | ✅ 10 भाषाएँ, इंटरैक्टिव सेलेक्टर | ❌ | ❌ | ❌ |
-| **सेल्फ-वेरिफाइंग** | ✅ 5 वैलिडेशन टूल्स | ❌ | ❌ | ❌ |
-| **बैकअप / रीस्टोर** | ✅ Master Plan सिस्टम | ❌ | ❌ | ❌ |
-| **सेटअप समय** | ~5–18 मिनट (ऑटोमेटेड) | ~5 मिनट (मैन्युअल कॉन्फ़िग) | घंटे–दिन | ~5 मिनट |
+| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
+|---|---|---|---|---|---|
+| **Approach** | Code analyzes first, then LLM generates | Pre-built config presets | LLM designs agent teams | LLM generates spec docs | LLM writes CLAUDE.md |
+| **Reads your source code** | ✅ Deterministic static analysis | ❌ | ❌ | ❌ (LLM reads) | ❌ (LLM reads) |
+| **Stack detection** | Code confirms (ORM, DB, build tool, pkg manager) | N/A (stack-agnostic) | LLM guesses | LLM guesses | LLM guesses |
+| **Domain detection** | Code confirms (Java 5 patterns, Kotlin CQRS, Next.js FSD) | N/A | LLM guesses | N/A | N/A |
+| **Same project → Same result** | ✅ Deterministic analysis | ✅ (static files) | ❌ (LLM varies) | ❌ (LLM varies) | ❌ (LLM varies) |
+| **Large project handling** | Domain group splitting (4 domains / 40 files per group) | N/A | No splitting | No splitting | Context window limit |
+| **Output** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ files) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 spec documents | CLAUDE.md (1 file) |
+| **Output location** | `.claude/rules/` (auto-loaded by Claude Code) | `.claude/` various | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
+| **Post-generation verification** | ✅ 5 automated validators | ❌ | ❌ | ❌ | ❌ |
+| **Multi-language output** | ✅ 10 languages | ❌ | ❌ | ❌ | ❌ |
+| **Multi-stack** | ✅ Backend + Frontend simultaneous | ❌ Stack-agnostic | ❌ | ❌ | Partial |
+| **Agent orchestration** | ❌ | ✅ 28 agents | ✅ 6 patterns | ❌ | ❌ |
 
----
+### Key difference
 
+**Other tools give Claude "generally good instructions." ClaudeOS-Core gives Claude "instructions extracted from your actual code."**
+
+### Complementary, not competing
+
+ClaudeOS-Core: **project-specific rules**. Other tools: **agent orchestration**.
+Use both together.
+
+---
 ## FAQ
 
 **प्र: क्या यह मेरा सोर्स कोड मॉडिफाई करता है?**

package/README.ja.md

@@ -1,6 +1,6 @@
 # ClaudeOS-Core
 
-**コマンド一発。ソースコードから Claude Code ドキュメントを完全自動生成。**
+**ソースコードを先に読み、スタックとパターンを決定論的分析で確定してから、プロジェクトに正確に合った Claude Code ルールを生成する唯一のツール。**
 
 ```bash
 npx claudeos-core init
@@ -12,20 +12,60 @@ ClaudeOS-Core はコードベースを読み取り、すべてのパターンを
 
 ---
 
-## 課題
+## なぜ ClaudeOS-Core なのか？
 
-Claude Code は強力ですが、_あなたの_ プロジェクトの規約を知りません。`CLAUDE.md` や数十のルール、スキャフォールディングスキルを手動で書くには何時間もかかり、コードベースが進化した瞬間に陳腐化します。
+他のすべての Claude Code ツールはこう動作します：
 
-## ソリューション
+> **人間がプロジェクトを説明 → LLM がドキュメントを生成**
 
-ClaudeOS-Core がプロセス全体を自動化します：
+ClaudeOS-Core はこう動作します：
 
-1. **スキャン** — スタック、ドメイン、ORM、DB、パッケージマネージャーを自動検出
-2. **ディープ分析** — コントローラーパターン、サービス層、命名規則、エラーハンドリング、セキュリティ、テストなど 50+ カテゴリ
-3. **生成** — `CLAUDE.md`、Standards（15–19 ファイル）、Rules、Skills、Guides（9 ファイル）、Master Plans、DB ドキュメント、MCP ガイドの完全な文書エコシステム
-4. **検証** — 5 つの組み込み検証ツールが整合性を保証
+> **コードがソースを分析 → コードがカスタムプロンプトを構築 → LLM がドキュメントを生成 → コードが出力を検証**
 
-所要時間：プロジェクト規模に応じて **5–18 分**。手動設定ゼロ。
+これは小さな違いではありません。
+
+### 核心的な問題：LLM は推測する。コードは確定する。
+
+Claude に「このプロジェクトを分析して」と頼むと、スタック、ORM、ドメイン構造を**推測**します。
+`build.gradle` で `spring-boot` を見ても、MyBatis ではなく JPA と誤認する可能性があります。
+`user/` ディレクトリを見ても、layer-first（Pattern A）か domain-first（Pattern B）か間違える可能性があります。
+
+**ClaudeOS-Core は推測しません。** Claude がプロジェクトを見る前に、Node.js コードがすでに：
+
+- `build.gradle` / `package.json` / `pyproject.toml` をパースしてスタック、ORM、DB、パッケージマネージャーを**確定**
+- ディレクトリ構造をスキャンしてドメインリストとファイル数を**確定**
+- プロジェクト構造を Java 5パターン、Kotlin CQRS/BFF、Next.js App Router/FSD のいずれかに**分類**
+- Claude のコンテキストウィンドウに収まるようドメインを最適グループに**分割**
+- 確定した事実が注入されたスタック固有のプロンプトを**構築**
+
+Claude がプロンプトを受け取る時点で、推測の余地はありません。スタック確定。ドメイン確定。構造パターン確定。Claude は**確定された事実**に沿ったドキュメントを生成するだけです。
+
+### 結果
+
+他のツールは「一般的に良い」ドキュメントを生成します。
+ClaudeOS-Core は、プロジェクトが `ApiResponse.ok()` を使用していること、MyBatis XML マッパーが `src/main/resources/mapper/{domain}/` にあること、パッケージ構造が `com.company.module.{domain}.controller` であることを知っているドキュメントを生成します — 実際のコードを読んだからです。
+
+### Before & After
+
+**ClaudeOS-Core なし** — Claude Code に注文 CRUD の作成を依頼すると：
+```
+❌ JPA スタイルの repository を使用（プロジェクトは MyBatis）
+❌ ResponseEntity.success() を生成（ラッパーは ApiResponse.ok()）
+❌ order/controller/ にファイルを配置（プロジェクトは controller/order/）
+❌ 英語コメントを生成（チームは日本語を使用）
+→ 生成ファイルごとに20分の修正
+```
+
+**ClaudeOS-Core 適用後** — `.claude/rules/` に確定されたパターンが存在：
+```
+✅ MyBatis マッパー + XML を生成（build.gradle から検出）
+✅ ApiResponse.ok() を使用（実際のソースから抽出）
+✅ controller/order/ にファイルを配置（構造スキャンで Pattern A 確定）
+✅ 日本語コメント（--lang ja 適用）
+→ 生成コードがプロジェクト規約と即座に一致
+```
+
+この差は蓄積されます。1日10タスク × 20分節約 = **1日3時間以上**。
 
 ---
 
@@ -79,6 +119,7 @@ Gradle マルチモジュール構造の Kotlin プロジェクト（例：CQRS
 - **FSD（Feature-Sliced Design）**：`features/*/`、`widgets/*/`、`entities/*/`
 - **RSC/Client分離**：`client.tsx` パターンを検出、サーバー/クライアントコンポーネントの分離を追跡
 - **設定ファイルフォールバック**：`package.json` になくても設定ファイルから Next.js/Vite/Nuxt を検出（monorepo対応）
+- **深層ディレクトリフォールバック**：React/CRA/Vite/Vue/RNプロジェクトで `**/components/*/`、`**/views/*/`、`**/screens/*/`、`**/containers/*/`、`**/pages/*/`、`**/routes/*/`、`**/modules/*/`、`**/domains/*/` を任意の深さでスキャン
 
 ---
 
@@ -117,7 +158,7 @@ bash claudeos-core-tools/bootstrap.sh
 
 ### 出力言語（10 言語対応）
 
-`--lang` なしで `init` を実行すると、矢印キーで言語を選択するインタラクティブ画面が表示されます：
+`--lang` なしで `init` を実行すると、矢印キーまたは数字キーで言語を選択するインタラクティブ画面が表示されます：
 
 ```
 ╔══════════════════════════════════════════════════╗
@@ -133,10 +174,10 @@ bash claudeos-core-tools/bootstrap.sh
   ❯  4. ja     — 日本語 (Japanese)
      ...
 
-  ↑↓ Move  ↵ Select
+  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
 ```
 
-矢印キーで移動すると、説明が該当言語に切り替わります。セレクターをスキップするには `--lang` を直接指定してください：
+選択を移動すると、説明が該当言語に切り替わります。セレクターをスキップするには `--lang` を直接指定してください：
 
 ```bash
 npx claudeos-core init --lang ja    # 日本語
@@ -388,16 +429,21 @@ ClaudeOS-Core が生成したドキュメントを Claude Code が実際に読
 | ファイル | タイミング | 保証 |
 |---|---|---|
 | `CLAUDE.md` | 毎回の会話開始時 | 常に |
-| `.claude/rules/*.md` | ファイル編集時（`paths: ["**/*"]`） | 常に |
-| `.claude/rules/00.core/00.standard-reference.md` | ↑ 上記に含まれる | 常に |
+| `.claude/rules/00.core/*` | ファイル編集時（`paths: ["**/*"]`） | 常に |
+| `.claude/rules/10.backend/*` | ファイル編集時（`paths: ["**/*"]`） | 常に |
+| `.claude/rules/30.security-db/*` | ファイル編集時（`paths: ["**/*"]`） | 常に |
+| `.claude/rules/40.infra/*` | config/infraファイル編集時のみ（スコープ付きpaths） | 条件付き |
+| `.claude/rules/50.sync/*` | claudeos-coreファイル編集時のみ（スコープ付きpaths） | 条件付き |
 
-### standard-reference ルール経由で読み取るファイル
+### ルール参照によるオンデマンド読み取り
 
-`00.standard-reference.md` ルールが、コード作成前に以下のドキュメントを Read するよう指示します：
+各ルールファイル末尾の `## Reference` セクションが対応するstandardをリンクします。Claudeは現在のタスクに関連するstandardのみ読み取ります：
 
 - `claudeos-core/standard/**` — コーディングパターン、✅/❌ 例、命名規則
 - `claudeos-core/database/**` — DB スキーマ（クエリ、マッパー、マイグレーション用）
 
+`00.standard-reference.md` は対応ルールのないstandardを発見するためのディレクトリです。
+
 ### 読み取らないファイル（コンテキスト節約）
 
 standard-reference ルールの `DO NOT Read` セクションで明示的に除外されます：
@@ -451,19 +497,39 @@ npx claudeos-core restore
 
 ## 何が違うのか？
 
-| | ClaudeOS-Core | SuperClaude | 手動 CLAUDE.md | 汎用 Skills |
-|---|---|---|---|---|
-| **コードを読む** | ✅ ディープ分析（55–95 カテゴリ） | ❌ 動作注入 | ❌ 手動作成 | ❌ 既製テンプレート |
-| **プロジェクト固有の出力** | ✅ すべてのファイルがあなたのパターンを反映 | ❌ 汎用コマンド | 部分的 | ❌ 画一的 |
-| **マルチスタック** | ✅ 自動検出 + 個別分析 | ❌ スタック非依存 | 手動 | 不定 |
-| **Kotlin + CQRS/BFF** | ✅ マルチモジュール、Command/Query分離 | ❌ | ❌ | ❌ |
-| **多言語対応** | ✅ 10 言語、インタラクティブ選択 | ❌ | ❌ | ❌ |
-| **自己検証** | ✅ 5 つの検証ツール | ❌ | ❌ | ❌ |
-| **バックアップ / リストア** | ✅ Master Plan システム | ❌ | ❌ | ❌ |
-| **セットアップ時間** | ~5–18分（自動） | ~5分（手動設定） | 数時間–数日 | ~5分 |
+### 他の Claude Code ツールとの比較
 
----
+| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
+|---|---|---|---|---|---|
+| **アプローチ** | コードが先に分析、LLMが生成 | 既製設定プリセット | LLMがエージェントチーム設計 | LLMがスペック文書生成 | LLMがCLAUDE.md作成 |
+| **ソースコード直接分析** | ✅ Deterministic 静的分析 | ❌ | ❌ | ❌ (LLMが読む) | ❌ (LLMが読む) |
+| **スタック検出** | コードが確定 (ORM, DB, ビルドツール, パッケージマネージャー) | N/A (スタック非依存) | LLMが推測 | LLMが推測 | LLMが推測 |
+| **ドメイン検出** | コードが確定 (Java 5パターン, Kotlin CQRS, Next.js FSD) | N/A | LLMが推測 | N/A | N/A |
+| **同じプロジェクト → 同じ結果** | ✅ Deterministic 分析 | ✅ (静的ファイル) | ❌ (LLM結果が変動) | ❌ (LLM結果が変動) | ❌ (LLM結果が変動) |
+| **大規模プロジェクト** | ドメイングループ分割 (4 ドメイン / 40 ファイル) | N/A | 分割なし | 分割なし | コンテキストウィンドウ制限 |
+| **出力** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ ファイル) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 スペック文書 | CLAUDE.md (1 ファイル) |
+| **出力場所** | `.claude/rules/` (Claude Code自動ロード) | `.claude/` 各所 | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
+| **生成後検証** | ✅ 5 自動検証ツール | ❌ | ❌ | ❌ | ❌ |
+| **多言語出力** | ✅ 10 言語 | ❌ | ❌ | ❌ | ❌ |
+| **マルチスタック** | ✅ バックエンド + フロントエンド同時 | ❌ スタック非依存 | ❌ | ❌ | 部分的 |
+| **エージェントオーケストレーション** | ❌ | ✅ 28 エージェント | ✅ 6 パターン | ❌ | ❌ |
+
+### 核心的な違い一言
 
+**他のツールは Claude に「一般的に良い指示」を与えます。ClaudeOS-Core は Claude に「実際のコードから抽出した指示」を与えます。**
+
+だから Claude Code が MyBatis プロジェクトで JPA コードを生成することがなくなり、
+`success()` の代わりに `ok()` を使うミスがなくなり、
+`controller/user/` 構造なのに `user/controller/` を作ることがなくなります。
+
+### 競合ではなく補完
+
+ClaudeOS-Core は**プロジェクト固有のルールと標準**に集中します。
+他のツールは**エージェントオーケストレーションとワークフロー**に集中します。
+
+ClaudeOS-Core でプロジェクトルールを生成し、その上に ECC や Harness を載せてエージェントチームとワークフロー自動化を構成できます。異なる問題を解決するツールです。
+
+---
 ## FAQ
 
 **Q：ソースコードは変更されますか？**

package/README.ko.md

@@ -1,6 +1,6 @@
 # ClaudeOS-Core
 
-**명령어 하나로. 실제 소스코드에서 Claude Code 문서 전체를 자동 생성합니다.**
+**소스코드를 먼저 읽고, 스택과 패턴을 코드로 확정한 뒤, 프로젝트에 정확히 맞는 Claude Code 규칙을 생성하는 유일한 도구.**
 
 ```bash
 npx claudeos-core init
@@ -13,20 +13,60 @@ ClaudeOS-Core는 코드베이스를 읽고, 발견한 모든 패턴을 추출하
 
 ---
 
-## 문제
+## 왜 ClaudeOS-Core인가?
 
-Claude Code는 강력하지만, _여러분_ 프로젝트의 컨벤션을 모릅니다. `CLAUDE.md`, 수십 개의 규칙, 스캐폴딩 스킬을 수동으로 작성하려면 몇 시간이 걸리고 — 코드베이스가 발전하는 순간 낡아버립니다.
+다른 모든 Claude Code 도구는 이렇게 작동합니다:
 
-## 해결책
+> **사람이 프로젝트를 설명 → LLM이 문서 생성**
 
-ClaudeOS-Core가 전체 프로세스를 자동화합니다:
+ClaudeOS-Core는 이렇게 작동합니다:
 
-1. **스캔** — 스택, 도메인, ORM, DB, 패키지 매니저를 자동 감지
-2. **분석** — 컨트롤러 패턴, 서비스 레이어, 명명 규칙, 에러 처리, 보안, 테스트 등 50개+ 카테고리 심층 분석
-3. **생성** — `CLAUDE.md`, Standards (15–19개 파일), Rules, Skills, Guides (9개 파일), Master Plans, DB 문서, MCP 가이드 완전 생성
-4. **검증** — 5개 내장 검증 도구로 일관성 자동 확인
+> **코드가 소스를 분석 → 코드가 맞춤 프롬프트 조합 → LLM이 문서 생성 → 코드가 결과 검증**
 
-총 소요 시간: 프로젝트 규모에 따라 **5–18분**. 수동 설정 불필요.
+이건 작은 차이가 아닙니다.
+
+### 핵심 문제: LLM은 추측한다. 코드는 확정한다.
+
+Claude에게 "이 프로젝트 분석해줘"라고 하면, 스택, ORM, 도메인 구조를 **추측**합니다.
+`build.gradle`에서 `spring-boot`를 보고도 MyBatis가 아닌 JPA로 오인할 수 있습니다.
+`user/` 디렉토리를 보고도 layer-first(Pattern A)인지 domain-first(Pattern B)인지 착각할 수 있습니다.
+
+**ClaudeOS-Core는 추측하지 않습니다.** Claude가 프로젝트를 보기 전에, Node.js 코드가 이미:
+
+- `build.gradle` / `package.json` / `pyproject.toml`을 파싱하여 스택, ORM, DB, 패키지 매니저를 **확정**
+- 디렉토리 구조를 스캔하여 도메인 목록과 파일 수를 **확정**
+- 프로젝트 구조를 Java 5패턴, Kotlin CQRS/BFF, Next.js App Router/FSD 중 하나로 **분류**
+- Claude의 컨텍스트 윈도우에 맞게 도메인을 최적 그룹으로 **분할**
+- 확정된 사실이 주입된 스택별 맞춤 프롬프트를 **조합**
+
+Claude가 프롬프트를 받는 시점에는 추측할 것이 없습니다. 스택 확정. 도메인 확정. 구조 패턴 확정. Claude는 이 **확정된 사실**에 맞는 문서를 생성하기만 하면 됩니다.
+
+### 결과
+
+다른 도구는 "일반적으로 좋은" 문서를 생성합니다.
+ClaudeOS-Core는 프로젝트가 `ApiResponse.ok()`를 쓴다는 것, MyBatis XML 매퍼가 `src/main/resources/mapper/{domain}/`에 있다는 것, 패키지 구조가 `com.company.module.{domain}.controller`라는 것을 아는 문서를 생성합니다 — 실제 코드를 읽었으니까요.
+
+### Before & After
+
+**ClaudeOS-Core 없이** — Claude Code에게 주문 CRUD 생성을 요청하면:
+```
+❌ JPA 스타일 repository 사용 (프로젝트는 MyBatis 사용)
+❌ ResponseEntity.success() 생성 (프로젝트 래퍼는 ApiResponse.ok())
+❌ order/controller/에 파일 배치 (프로젝트는 controller/order/ 구조)
+❌ 영어 주석 생성 (팀은 한국어 주석 사용)
+→ 생성된 파일마다 20분씩 수정
+```
+
+**ClaudeOS-Core 적용 후** — `.claude/rules/`에 확정된 패턴이 이미 존재:
+```
+✅ MyBatis 매퍼 + XML 생성 (build.gradle에서 감지)
+✅ ApiResponse.ok() 사용 (실제 소스에서 추출)
+✅ controller/order/에 파일 배치 (구조 스캔으로 Pattern A 확정)
+✅ 한국어 주석 (--lang ko 적용)
+→ 생성 코드가 프로젝트 컨벤션과 즉시 일치
+```
+
+이 차이는 누적됩니다. 하루 10개 작업 × 20분 절약 = **하루 3시간 이상**.
 
 ---
 
@@ -79,6 +119,7 @@ Gradle 멀티모듈 구조의 Kotlin 프로젝트(예: CQRS 모노레포)용:
 - **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
 - **RSC/Client 분리**: `client.tsx` 패턴 감지, Server/Client 컴포넌트 분리 추적
 - **설정 파일 폴백**: `package.json`에 없어도 `next.config.*`, `vite.config.*` 등에서 감지 (모노레포 지원)
+- **깊은 디렉토리 폴백**: React/CRA/Vite/Vue/RN 프로젝트에서 `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/`를 깊이 무관하게 스캔
 
 ---
 
@@ -117,7 +158,7 @@ bash claudeos-core-tools/bootstrap.sh
 
 ### 출력 언어 (10개 언어 지원)
 
-`--lang` 없이 `init`을 실행하면 화살표 키로 언어를 선택하는 인터랙티브 화면이 나타납니다:
+`--lang` 없이 `init`을 실행하면 화살표 키 또는 숫자 키로 언어를 선택하는 인터랙티브 화면이 나타납니다:
 
 ```
 ╔══════════════════════════════════════════════════╗
@@ -132,10 +173,10 @@ bash claudeos-core-tools/bootstrap.sh
      3. zh-CN  — 简体中文 (Chinese Simplified)
      ...
 
-  ↑↓ Move  ↵ Select
+  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
 ```
 
-화살표 이동 시 설명이 해당 언어로 바뀝니다. 선택 화면을 건너뛰려면 `--lang`을 직접 지정하세요:
+이동 시 설명이 해당 언어로 바뀝니다. 선택 화면을 건너뛰려면 `--lang`을 직접 지정하세요:
 
 ```bash
 npx claudeos-core init --lang ko    # 한국어
@@ -405,16 +446,21 @@ ClaudeOS-Core가 생성한 문서를 Claude Code가 실제로 읽는 방식입
 | 파일 | 시점 | 보장 |
 |---|---|---|
 | `CLAUDE.md` | 매 대화 시작 시 | 항상 |
-| `.claude/rules/*.md` | 파일 편집 시 (`paths: ["**/*"]`) | 항상 |
-| `.claude/rules/00.core/00.standard-reference.md` | ↑ 위에 포함 | 항상 |
+| `.claude/rules/00.core/*` | 파일 편집 시 (`paths: ["**/*"]`) | 항상 |
+| `.claude/rules/10.backend/*` | 파일 편집 시 (`paths: ["**/*"]`) | 항상 |
+| `.claude/rules/30.security-db/*` | 파일 편집 시 (`paths: ["**/*"]`) | 항상 |
+| `.claude/rules/40.infra/*` | config/infra 파일 편집 시만 (스코핑된 paths) | 조건부 |
+| `.claude/rules/50.sync/*` | claudeos-core 파일 편집 시만 (스코핑된 paths) | 조건부 |
 
-### standard-reference 규칙을 통해 읽는 파일
+### rule 참조를 통해 온디맨드로 읽는 파일
 
-`00.standard-reference.md` 규칙이 Claude Code에게 코드 작성 전 아래 문서를 Read하도록 지시합니다:
+각 rule 파일 하단의 `## Reference` 섹션이 대응하는 standard를 링크합니다. Claude는 현재 작업과 관련된 standard만 읽습니다:
 
 - `claudeos-core/standard/**` — 코딩 패턴, ✅/❌ 예시, 네이밍 규칙
 - `claudeos-core/database/**` — DB 스키마 (쿼리, 매퍼, 마이그레이션용)
 
+`00.standard-reference.md`는 대응 rule이 없는 standard를 발견하기 위한 디렉토리 역할입니다.
+
 ### 읽지 않는 파일 (컨텍스트 절약)
 
 standard-reference 규칙의 `DO NOT Read` 섹션으로 명시적으로 제외됩니다:
@@ -468,19 +514,39 @@ npx claudeos-core restore
 
 ## 무엇이 다른가?
 
-| | ClaudeOS-Core | SuperClaude | 수동 CLAUDE.md | 제네릭 스킬 |
-|---|---|---|---|---|
-| **코드 분석** | ✅ 심층 분석 (55–95 카테고리) | ❌ 행동 주입 | ❌ 수동 작성 | ❌ 사전 제작 템플릿 |
-| **프로젝트 특화 출력** | ✅ 모든 파일이 실제 패턴 반영 | ❌ 제네릭 명령어 | 부분적 | ❌ 획일적 |
-| **멀티스택** | ✅ 자동 감지 + 별도 분석 | ❌ 스택 무관 | 수동 | 다양 |
-| **Kotlin + CQRS/BFF** | ✅ 멀티모듈, Command/Query 분리 | ❌ | ❌ | ❌ |
-| **다국어 지원** | ✅ 10개 언어, 인터랙티브 선택 | ❌ | ❌ | ❌ |
-| **자체 검증** | ✅ 5개 검증 도구 | ❌ | ❌ | ❌ |
-| **백업 / 복원** | ✅ Master Plan 시스템 | ❌ | ❌ | ❌ |
-| **설정 시간** | ~5–18분 (자동화) | ~5분 (수동 설정) | 수 시간–며칠 | ~5분 |
+### 다른 Claude Code 도구와의 비교
 
----
+| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
+|---|---|---|---|---|---|
+| **접근 방식** | 코드가 먼저 분석 후 LLM 생성 | 사전 제작된 설정 프리셋 | LLM이 에이전트 팀 설계 | LLM이 스펙 문서 생성 | LLM이 CLAUDE.md 작성 |
+| **소스코드 직접 분석** | ✅ Deterministic 정적 분석 | ❌ | ❌ | ❌ (LLM이 읽음) | ❌ (LLM이 읽음) |
+| **스택 감지** | 코드가 확정 (ORM, DB, 빌드 툴, 패키지 매니저) | N/A (스택 무관) | LLM이 추측 | LLM이 추측 | LLM이 추측 |
+| **도메인 감지** | 코드가 확정 (Java 5패턴, Kotlin CQRS, Next.js FSD) | N/A | LLM이 추측 | N/A | N/A |
+| **같은 프로젝트 → 같은 결과** | ✅ Deterministic 분석 | ✅ (정적 파일) | ❌ (LLM 결과 변동) | ❌ (LLM 결과 변동) | ❌ (LLM 결과 변동) |
+| **대형 프로젝트 처리** | 도메인 그룹 분할 (4 도메인 / 40 파일) | N/A | 분할 없음 | 분할 없음 | 컨텍스트 윈도우 한계 |
+| **출력물** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ 파일) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 스펙 문서 | CLAUDE.md (1 파일) |
+| **출력 위치** | `.claude/rules/` (Claude Code 자동 로드) | `.claude/` 여러 위치 | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
+| **생성 후 검증** | ✅ 5 자동 검증 도구 | ❌ | ❌ | ❌ | ❌ |
+| **다국어 출력** | ✅ 10 언어 | ❌ | ❌ | ❌ | ❌ |
+| **멀티 스택** | ✅ 백엔드 + 프론트엔드 동시 | ❌ 스택 무관 | ❌ | ❌ | 부분적 |
+| **에이전트 오케스트레이션** | ❌ | ✅ 28 에이전트 | ✅ 6 패턴 | ❌ | ❌ |
+
+### 핵심 차이 한 줄
 
+**다른 도구는 Claude에게 "일반적으로 좋은 지침"을 줍니다. ClaudeOS-Core는 Claude에게 "실제 코드에서 추출한 지침"을 줍니다.**
+
+그래서 Claude Code가 MyBatis 프로젝트에서 JPA 코드를 생성하는 일이 없어지고,
+`success()`를 써야 할 곳에 `ok()`를 쓰는 일이 없어지고,
+`controller/user/` 구조인데 `user/controller/`로 만드는 일이 없어집니다.
+
+### 경쟁이 아닌 보완
+
+ClaudeOS-Core는 **프로젝트별 규칙과 표준**에 집중합니다.
+다른 도구들은 **에이전트 오케스트레이션과 워크플로우**에 집중합니다.
+
+ClaudeOS-Core로 프로젝트 규칙을 생성한 뒤, ECC나 Harness를 그 위에 얹어 에이전트 팀과 워크플로우 자동화를 구성할 수 있습니다. 서로 다른 문제를 해결하는 도구입니다.
+
+---
 ## FAQ
 
 **Q: 소스코드를 수정하나요?**