From 0095f447cf5eb3eba11a82c57c51ee2487a604eb Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 06:20:26 +0900 Subject: [PATCH 01/10] Add comprehensive FAQ for Be Framework with improved readability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create Japanese and English FAQ with 26+ questions covering core concepts - Fix technical accuracy about $being/$been properties (conventions, not magic) - Improve visual hierarchy with ### headers and **A.** format - Convert Japanese FAQ to polite desu/masu form for consistency - Reduce excessive bold formatting for better readability - Expand term glossary with detailed philosophical explanations - Add FAQ links to both language index pages - Fix Philosophy chapter category for consistent CSS styling 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- manuals/1.0/en/12-philosophy-behind.md | 2 +- manuals/1.0/en/faq.md | 208 +++++++++++++++++++++++++ manuals/1.0/en/index.md | 3 + 3 files changed, 212 insertions(+), 1 deletion(-) create mode 100644 manuals/1.0/en/faq.md diff --git a/manuals/1.0/en/12-philosophy-behind.md b/manuals/1.0/en/12-philosophy-behind.md index c7e5010..75a635a 100644 --- a/manuals/1.0/en/12-philosophy-behind.md +++ b/manuals/1.0/en/12-philosophy-behind.md @@ -1,7 +1,7 @@ --- layout: docs-en title: "12. The Philosophy Behind" -category: Philosophy +category: Manual permalink: /manuals/1.0/en/12-philosophy-behind.html --- diff --git a/manuals/1.0/en/faq.md b/manuals/1.0/en/faq.md new file mode 100644 index 0000000..e0b4091 --- /dev/null +++ b/manuals/1.0/en/faq.md @@ -0,0 +1,208 @@ +--- +layout: docs-en +title: "FAQ" +category: Manual +permalink: /manuals/1.0/en/faq.html +--- + +# Be Framework FAQ + +> Last updated: 2025-09-13 + +## 0) TL;DR + +**Q. Is this a new "programming paradigm"?** +A. **Yes (as a design paradigm)**. Built on top of OOP/FP/DDD, it's an **ontological programming model** that makes "whether something can exist (WHETHER?)" and "type = temporal state" first-class citizens. It's an orthogonal extension, not a replacement. + +--- + +## 1) Paradigm & Concepts + +**Q1. How is this different from MVC or DDD?** +A. MVC is a **structural pattern** for responsibility separation, DDD is a modeling **methodology**. +Be is a **design paradigm** centered on "existence conditions and temporal transformation," where flow **self-organizes** through `#[Be]` and `$being`. + +**Q2. Is this OOP or FP?** +A. It works with both. It emphasizes **immutability and referential transparency** while realizing **one-time complete transformation in constructors** (entelecheia) using OOP containers. + +**Q3. What's the benefit of defining "BEING (what something is)" first?** +A. It makes invalid states **impossible to generate** upfront (drastically reducing defensive if/guard statements). +**Type = reachable state** becomes API specification. + +**Q4. What does "type = temporal state" mean?** +A. Types like `ValidatedUser` / `SavedUser` / `DeletedUser` express the **"when" in progress**. +Time and domain are inseparable (details: [Metamorphosis](./05-metamorphosis.html)). + +--- + +## 2) Core Features + +**Q5. What does `#[Be]` do?** +A. It declares **destiny (what to become next)**. +Given single/multiple candidates, the continuation is **automatically selected** at runtime by the type of `$being`. +(Reference: [Type-Driven Metamorphosis](./07-type-driven-metamorphosis.html)) + +**Q6. What's the role of the `$being` property?** +A. It holds the **next existence** that the current existence leads to. Union types **explicitly show all possibilities** of results. + +**Q6.5. Are `$being` and `$been` specially treated properties?** +A. No. These are not magically interpreted by the framework—they are mere conventions. + +`becoming()` doesn't read property names, but looks at the **types declared on properties** to select the next class. + +Therefore, the names `$being` / `$been` are not required. `public Success|Failure $result;` works the same way with different names. + +However, using these names according to documentation, samples, and design philosophy provides the benefit of immediately recognizing **"transformation destination (being)"** and **"completion evidence (been)"**. + +**Actual behavior**: +- `$being`: Conventional property name for holding "which type it transformed to next" +- `$been`: Conventional property name for holding "completion self-proof" (past perfect meaning) + +**Q8. What are "Semantic Variables"?** +A. Variable name = **meaning + constraints**. `$email` must be a "valid Email" to **exist**. +It **integrates into types** validations that tend to scatter (controller/validator/docs). +([Semantic Variables](./06-semantic-variables.html)) + +**Q9. What is the "Reason Layer"?** +A. It injects **the foundation = tool set** that enables a certain existence state as objects. +It **bundles related tools meaningfully** from traditional individual DI, improving testability. +([Reason Layer](./08-reason-layer.html)) + +**Q10. What is `$been` (self-proof) for?** +A. It **internally contains** the trail of that existence's **completion** (who, when, what). +It aligns well with external tests and audit logs. +([Final Objects](./04-final-objects.html)) + +--- + +## 3) Design & Implementation + +**Q11. Where do side effects occur?** +A. Principally **completed by delegating to Reason within constructors**. This eliminates the need for external orchestrators and huge service layers. + +**Q12. How are exceptions handled?** +A. Using **semantic exceptions** that hold failures as collections (supporting multilingual messages). "Partial success/partial failure" can also be expressed as **valid existence** of **Invalid~**. ([Error Handling](./09-error-handling.html)) + +**Q13. What's the testing strategy?** +A. Verify each existence (type) **individually**. Preconditions = `#[Input]`, postconditions = `public` properties. Use cases can be kept sufficiently thin with **`#[Be]` chain** smoke tests. + +**Q14. What about performance?** +A. Philosophy of **composing** immutable, fine-grained existences. While there's DI cost, it's net positive through **side effect localization** and **bug reduction**. Hot paths can be optimized in Reason implementations. + +**Q15. When to choose "linear," "branching," or "nested"?** +A. Procedure-dependent = **linear** / Results exclusive by conditions = **branching** / Convergence of independent processes = **nested**. When in doubt, start with **minimal linear**. ([Implementation Guidelines](./05-metamorphosis.html)) + +--- + +## 4) Integration with Existing Assets + +**Q16. Can this be introduced to existing MVC apps?** +A. Yes. Replace the **Use Case layer** with Be, and just call `becoming(new …Input)` from Controllers. Gradually organize into **immanent/transcendent**. + +**Q17. Where do you use DB or external APIs?** +A. In **Reason**. Storage and transmission means are consolidated in Reason, **separated** from existence (state) definition. + +**Q18. Framework dependencies?** +A. Core uses PHP standard + DI (e.g., Ray.Di). Integration with Laravel/Symfony etc. is possible via **adapters**. + +**Q19. Do static analysis and IDE completion work?** +A. **Very well** since types are "states." Branching is made explicit with union types, and completion is safe too. + +--- + +## 5) Operations, Logging & Auditing + +**Q20. How are logs recorded?** +A. **Semantic logging** is recommended (Koriym.SemanticLogger integration). Record transformation (from/to/reason/evidence) as **structured JSON**. ([Semantic Logging](./10-semantic-logging.html)) + +**Q21. Audit compliance?** +A. `$been` (self-proof) + semantic logging can provide **complete audit trails**. Personal information follows **minimum privilege** principles at the Reason layer. + +--- + +## 6) Modeling Guidelines & Anti-patterns + +**Q22. Common pitfalls?** + +* Dumping everything into Reason (bloating) +* Mixing external dependencies into `Input` (polluting immanence) +* "Ambiguous state names" with unclear temporality (ambiguous words like `Processed?`) + +**Q23. When not to use Be?** +A. For one-off scripts / ultra-lightweight CRUD where **temporality and existence conditions are thin**, traditional approaches may be faster. + +--- + +## 7) Migration + +**Q24. Migration steps for existing code? (Minimal steps)** + +1. Choose one representative use case +2. Extract input as `…Input` (immanent only) +3. Design transformation target as `…` (existence), add `#[Be]` +4. Consolidate external dependencies into Reason +5. Call `becoming(new …Input)` from Controller +6. Migrate validation to semantic variables / replace exceptions semantically +7. Introduce semantic logging + +--- + +## 8) Future Features + +**Q25. What about `#[Accept]` (Extended Decision Making)?** +A. Conceptual stage. Plans to **delegate undeterminable decisions to experts or AI**, handling certainty and uncertainty in one framework. ([Type-Driven Metamorphosis](./07-type-driven-metamorphosis.html) end note) + +--- + +## 9) Examples & Snippets + +**Q26. Minimal example of typical flow?** + +```php +// 1) Input (immanent only) +#[Be(UserProfile::class)] +final readonly class UserInput { + public function __construct(public string $name, public string $email) {} +} + +// 2) Being (moment of transformation) +final readonly class UserProfile { + public function __construct( + #[Input] string $name, + #[Input] string $email, + #[Inject] NameFormatter $fmt, + #[Inject] EmailValidator $v + ) { + $this->display = $fmt->format($name); + $this->isValid = $v->validate($email); + } + public string $display; + public bool $isValid; +} + +// 3) Execution (self-organization) +$profile = $becoming(new UserInput($name, $email)); +``` + +--- + +## 10) Quick Term Index + +* **Being-oriented / Ontological**: Design perspective making existence possibility and time primary abstractions. +* **Immanence / Transcendence**: Intrinsic properties / Forces provided from outside. +* **Entelecheia**: The "moment of transformation" when potential moves to actual. +* **Reason Layer**: Foundation (tool set) for state establishment. +* **Semantic Variables**: Name = meaning = constraints. +* **Semantic Exceptions / Semantic Logging**: Holding failures and history with meaning. + +--- + +## 11) Related Chapter Links + +* **[Overview](./01-overview.html)**: First encounter with being-oriented programming +* **[Metamorphosis](./05-metamorphosis.html)**: Inseparability of time and domain +* **[Semantic Variables](./06-semantic-variables.html)**: Domain-specific validation and type safety +* **[Type-Driven Metamorphosis](./07-type-driven-metamorphosis.html)**: Self-determining objects +* **[Reason Layer](./08-reason-layer.html)**: Raison d'être and object existence foundations +* **[Error Handling](./09-error-handling.html)**: Semantic exceptions and multilingual messages +* **[Semantic Logging](./10-semantic-logging.html)**: Structured recording and audit trails \ No newline at end of file diff --git a/manuals/1.0/en/index.md b/manuals/1.0/en/index.md index f4301a9..d41ae9b 100644 --- a/manuals/1.0/en/index.md +++ b/manuals/1.0/en/index.md @@ -42,6 +42,9 @@ Structured recording and audit trails of object metamorphosis ## [11. Reference](./11-reference-resources.html) Essential resources and links for framework development +## [FAQ](./faq.html) +Frequently asked questions and answers + --- *"Be, Don't Do"* \ No newline at end of file From 90e3cc459117c914fd7340d731127742c36db331 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 06:20:36 +0900 Subject: [PATCH 02/10] Complete Japanese FAQ implementation with enhanced readability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Japanese FAQ with detailed term explanations - Convert all answers to polite desu/masu form - Remove excessive bold formatting for cleaner reading - Add comprehensive glossary with philosophical context - Fix Philosophy chapter category in Japanese version - Add FAQ link to Japanese index page 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- manuals/1.0/ja/12-philosophy-behind.md | 2 +- manuals/1.0/ja/faq.md | 296 +++++++++++++++++++++++++ manuals/1.0/ja/index.md | 3 + 3 files changed, 300 insertions(+), 1 deletion(-) create mode 100644 manuals/1.0/ja/faq.md diff --git a/manuals/1.0/ja/12-philosophy-behind.md b/manuals/1.0/ja/12-philosophy-behind.md index 7449ee0..9133ab5 100644 --- a/manuals/1.0/ja/12-philosophy-behind.md +++ b/manuals/1.0/ja/12-philosophy-behind.md @@ -1,7 +1,7 @@ --- layout: docs-ja title: "12. 背後にある哲学" -category: Philosophy +category: Manual permalink: /manuals/1.0/ja/12-philosophy-behind.html --- diff --git a/manuals/1.0/ja/faq.md b/manuals/1.0/ja/faq.md new file mode 100644 index 0000000..802e0d1 --- /dev/null +++ b/manuals/1.0/ja/faq.md @@ -0,0 +1,296 @@ +--- +layout: docs-ja +title: "FAQ" +category: Manual +permalink: /manuals/1.0/ja/faq.html +--- + +# Be Framework FAQ + +> 最終更新: 2025-09-13 + +## 0) 要旨（TL;DR） + +### Q. これは新しい"プログラミングパラダイム"ですか？ + +**A.** はい、設計パラダイムとしてです。 + +OOP/FP/DDDの上に「存在できるか（WHETHER?）」と「型＝時間的状態」を一次市民に据える存在論的プログラミングモデルです。置き換えではなく直交的な拡張となります。 + +--- + +## 1) パラダイム & 概念 + +### Q1. MVCやDDDとどう違いますか？ + +**A.** MVCは責務分割の構造パターン、DDDはモデリングの方法論です。 + +Be Frameworkは「存在条件と時間的変容」を中核に据える設計パラダイムで、`#[Be]`と`$being`によりフローが自己組織化されます。 + +### Q2. OOP/FPのどちらですか？ + +**A.** どちらにも適用できます。 + +不変性・参照透明性を重視しながら、コンストラクタでの一回完結の変容（エンテレケイア）をOOPの枠組みで実現しています。 + +### Q3. 「BEING（何であるか）」を先に定義する利点は？ + +**A.** 不正状態を事前に生成不能にできます。 + +防御的なif/guard文が激減し、型＝到達可能状態がAPI仕様となります。 + +### Q4. 「型＝時間的状態」とは何ですか？ + +**A.** `ValidatedUser`、`SavedUser`、`DeletedUser`など、進行中の"いつ"を型名で表現しています。 + +時間とドメインは不可分です。詳細は[メタモルフォーシス](./05-metamorphosis.html)をご覧ください。 + +--- + +## 2) 主要機能 + +### Q5. `#[Be]`属性は何をしますか？ + +**A.** オブジェクトの運命（次に何になるか）を宣言します。 + +単一または複数の変容候補を指定し、実行時に`$being`プロパティの型で継続先が自動選択されます。 + +詳しくは[型駆動変容](./07-type-driven-metamorphosis.html)をご参照ください。 + +### Q6. `$being`プロパティの役割は何ですか？ + +**A.** 現在の存在が導く次の存在を保持します。 + +ユニオン型を使用することで、結果の全可能性を明示しています。 + +### Q6.5. `$being`や`$been`は特別なプロパティですか？ + +**A.** いいえ、特別なプロパティではありません。 + +これらはフレームワークが魔法的に解釈するものではなく、**単なる規約**です。 + +`becoming()`関数はプロパティ名を読むのではなく、**プロパティに宣言された型**を見て次のクラスを選択します。 + +そのため、`$being`や`$been`という名前である必要はありません。`public Success|Failure $result;`のように別の名前でも同じように動作します。 + +ただし、ドキュメント・サンプル・設計思想に合わせてこの名前を使用することで、「変容先（being）」「完了の証跡（been）」が一目で分かるというメリットがあります。 + +### Q8. 「意味変数」とは何ですか？ + +**A.** 変数名＝意味＋制約です。`$email`は「有効なEmail」でなければ存在できません。 + +分散しがちな検証（controller/validator/docs）を型に統合します。 + +（詳細：[意味変数](./06-semantic-variables.html)） + +### Q9. 「存在理由層（Reason）」とは何ですか？ + +**A.** ある存在状態を成立させる根拠＝道具一式をオブジェクトとして注入します。 + +従来の個別DIを意味で束ねてテスト容易性を高めます。 + +（詳細：[存在理由層](./08-reason-layer.html)） + +### Q10. `$been`（自己証明）は何のためですか？ + +**A.** その存在が完了した証跡（誰が・いつ・何を）を内在させます。 + +外部テストや監査ログと整合しやすくなります。 + +（詳細：[最終オブジェクト](./04-final-objects.html)） + +--- + +## 3) 設計・実装 + +### Q11. どこで副作用を起こしますか？ + +**A.** 原則としてコンストラクタの中でReasonに委譲して完結させます。 + +外部オーケストレーターや巨大なservice層を不要にします。 + +### Q12. 例外はどう扱いますか？ + +**A.** 意味的例外を用いて、失敗を集合で保持します（多言語メッセージ対応）。 + +「部分成功・部分失敗」もInvalid〜の"有効な存在"として表現できます。 + +（詳細：[エラーハンドリング](./09-error-handling.html)） + +### Q13. テスト戦略はどのようになりますか？ + +**A.** 各存在（型）を単体で検証します。 + +事前条件＝`#[Input]`、事後条件＝`public`プロパティ。ユースケースは`#[Be]`連鎖のスモークで十分に薄く保てます。 + +### Q14. パフォーマンスはどうですか？ + +**A.** 不変・小粒度の存在を合成する思想です。 + +DIコストはありますが、副作用の局在化とバグ削減で総合的にプラスになります。ホットパスはReason実装で最適化可能です。 + +### Q15. いつ「線形」「分岐」「ネスト」を選びますか？ + +**A.** 手順依存=線形／条件で結果が排他的=分岐／独立処理の合流=ネストです。 + +迷ったら最小限の線形から始めることをお勧めします。 + +（詳細：[実装指針](./05-metamorphosis.html)） + +--- + +## 4) 既存資産との統合 + +### Q16. 既存のMVCアプリに導入できますか？ + +**A.** はい、可能です。UseCase層をBeで置き換えて、Controllerからは`becoming(new …Input)`を呼ぶだけです。 + +徐々に内在/超越へ整理していくことができます。 + +### Q17. DBや外部APIはどこで使いますか？ + +**A.** Reasonで使います。 + +保存や送信の手段はReasonに集約し、存在（状態）定義と分離します。 + +### Q18. フレームワーク依存はどうなりますか？ + +**A.** コアはPHP標準＋DI（例：Ray.Di）です。 + +Laravel/Symfony等へはアダプタで連携可能です。 + +### Q19. 静的解析やIDE補完は効きますか？ + +**A.** 型が"状態"なので非常に効きます。 + +ユニオン型で分岐が明示化され、補完も安全です。 + +--- + +## 5) 運用・ログ・監査 + +### Q20. ログはどう残りますか？ + +**A.** 意味的ログを推奨しています（Koriym.SemanticLogger連携）。 + +変容（from/to/理由/証跡）を構造化JSONで記録します。 + +（詳細：[意味的ログ](./10-semantic-logging.html)） + +### Q21. 監査対応はどうなりますか？ + +**A.** `$been`（自己証明）＋意味的ログで完全な監査証跡を提供可能です。 + +個人情報はReasonレイヤで最小権限を徹底します。 + +--- + +## 6) モデリング指針 & アンチパターン + +### Q22. よくある落とし穴は何ですか？ + +**A.** 以下のような点に注意が必要です： + +* なんでもかんでもReasonに丸投げする（肥大化） +* `Input`に外部依存を混入する（内在が汚れる） +* "状態名が曖昧"で時間性が不明確（`Processed?`などの曖昧語） + +### Q23. いつBeを使わない方がいいですか？ + +**A.** 単発スクリプト／超軽量なCRUDで時間性や存在条件が希薄な場合は、従来手法の方が速いことがあります。 + +--- + +## 7) マイグレーション + +### Q24. 既存コードの移行手順は何ですか？（最小ステップ） + +**A.** 以下の手順をお勧めします： + +1. 代表ユースケースを1つ選びます +2. 入力を`…Input`として抽出します（内在のみ） +3. 変換先を`…`（存在）として設計し、`#[Be]`を付与します +4. 外部依存をReasonに集約します +5. Controllerから`becoming(new …Input)`を呼びます +6. 意味変数へ検証を移管／例外を意味的に置換します +7. 意味的ログを導入します + +--- + +## 8) 将来機能 + +### Q25. `#[Accept]`（拡張意思決定）はどのような機能ですか？ + +**A.** 構想段階の機能です。 + +確定できない判断を専門家やAIへ委譲し、確定性と不確実性を一つのフレームで扱う予定です。 + +（詳細：[型駆動変容](./07-type-driven-metamorphosis.html)末尾の注記） + +--- + +## 9) 例とスニペット + +### Q26. 典型フローの最小例はどのようなものですか？ + +**A.** + +```php +// 1) 入力（内在のみ） +#[Be(UserProfile::class)] +final readonly class UserInput { + public function __construct(public string $name, public string $email) {} +} + +// 2) 存在（変容の瞬間） +final readonly class UserProfile { + public function __construct( + #[Input] string $name, + #[Input] string $email, + #[Inject] NameFormatter $fmt, + #[Inject] EmailValidator $v + ) { + $this->display = $fmt->format($name); + $this->isValid = $v->validate($email); + } + public string $display; + public bool $isValid; +} + +// 3) 実行（自己組織化） +$profile = $becoming(new UserInput($name, $email)); +``` + +--- + +## 10) 重要用語の詳細解説 + +### 存在指向 / Ontological（オントロジカル） +存在可能性と時間を一次の抽象として扱う設計観念です。従来の「何をするか」ではなく「何が存在できるか」を中心に据えた思考法で、プログラムの状態を時間的な存在として捉えます。 + +### イマナンス / トランセンデンス（内在 / 超越） +イマナンス（内在）は、オブジェクトが本来持っている性質や情報を指します。トランセンデンス（超越）は、外部環境や依存関係から与えられる能力や情報を指します。Be Frameworkでは、この二つの組み合わせによって新しい存在が生まれます。 + +### エンテレケイア（Entelecheia） +アリストテレス哲学に由来する概念で、潜在性が現実性へ移行する「変容の瞬間」を表します。Be Frameworkでは、コンストラクタで内在と超越が出会って新しい存在が完成する瞬間を指します。 + +### 存在理由層（Reason Layer） +ある存在状態が成立するために必要な根拠や道具一式をオブジェクトとして集約したものです。従来のDI（依存注入）を意味でまとめて、テスト容易性と保守性を高めます。 + +### 意味変数（Semantic Variables） +変数名そのものが意味と制約を表現する概念です。例えば`$validEmail`は「有効なEmail」でなければ存在できないという制約を名前で表現し、分散しがちな検証ロジックを型レベルで統合します。 + +### 意味的例外 / 意味的ログ +失敗や履歴を単純な文字列ではなく、意味を持った構造化されたデータとして保持する仕組みです。多言語対応や監査要件に対応し、システムの動作を意味レベルで追跡可能にします。 + +--- + +## 11) 関連章へのリンク + +* **[概要](./01-overview.html)**: 存在指向プログラミングとの出会い +* **[メタモルフォーシス](./05-metamorphosis.html)**: 時間とドメインの不可分性 +* **[意味変数](./06-semantic-variables.html)**: ドメイン固有の検証と型安全性 +* **[型駆動変容](./07-type-driven-metamorphosis.html)**: 自己決定オブジェクト +* **[存在理由層](./08-reason-layer.html)**: オブジェクトの存在根拠 +* **[エラーハンドリング](./09-error-handling.html)**: 意味的例外と多言語メッセージ +* **[意味的ログ](./10-semantic-logging.html)**: 構造化記録と監査証跡 diff --git a/manuals/1.0/ja/index.md b/manuals/1.0/ja/index.md index 1da92fc..491eb89 100644 --- a/manuals/1.0/ja/index.md +++ b/manuals/1.0/ja/index.md @@ -41,6 +41,9 @@ permalink: /manuals/1.0/ja/ ## [11. リファレンス](./11-reference-resources.html) フレームワーク開発に必要なリソースとリンク集 +## [FAQ](./faq.html) +よくある質問と回答集 + --- > Be, Don't Do From a8542f53f541b8afce15c4f1f7be174739e81907 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 07:31:01 +0900 Subject: [PATCH 03/10] Refine FAQ with balanced approach: preserve conciseness while enhancing clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve Q0 answer with clear DO vs BE paradigm contrast - Add missing Q7 about metamorphosis chain control - Return to simple "A." format for better readability - Maintain original compactness while keeping key improvements - Update both Japanese and English versions consistently 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- manuals/1.0/en/faq.md | 4 ++- manuals/1.0/ja/faq.md | 70 ++++++++++++++++++++++++------------------- 2 files changed, 43 insertions(+), 31 deletions(-) diff --git a/manuals/1.0/en/faq.md b/manuals/1.0/en/faq.md index e0b4091..12fb686 100644 --- a/manuals/1.0/en/faq.md +++ b/manuals/1.0/en/faq.md @@ -12,7 +12,9 @@ permalink: /manuals/1.0/en/faq.html ## 0) TL;DR **Q. Is this a new "programming paradigm"?** -A. **Yes (as a design paradigm)**. Built on top of OOP/FP/DDD, it's an **ontological programming model** that makes "whether something can exist (WHETHER?)" and "type = temporal state" first-class citizens. It's an orthogonal extension, not a replacement. +A. **Yes**. Be Framework proposes BE-oriented programming ("Whether?" = can this state exist?) in contrast to traditional DO-oriented approaches (Imperative = "How?", OOP = "Who?", FP = "What?"). + +It makes temporal existence first-class citizens and designs based on "what something is" rather than "what it does." While it's a significant paradigm shift philosophically, implementation-wise it coexists with OOP/FP/DDD and doesn't require replacing existing styles. --- diff --git a/manuals/1.0/ja/faq.md b/manuals/1.0/ja/faq.md index 802e0d1..00e85d4 100644 --- a/manuals/1.0/ja/faq.md +++ b/manuals/1.0/ja/faq.md @@ -13,9 +13,9 @@ permalink: /manuals/1.0/ja/faq.html ### Q. これは新しい"プログラミングパラダイム"ですか？ -**A.** はい、設計パラダイムとしてです。 +A. はい。Be Frameworkは、従来のDO指向（Imperative = "How?", OOP = "Who?", FP = "What?"）に対して、BE指向（"Whether?" = その状態は存在できるか）を提案します。 -OOP/FP/DDDの上に「存在できるか（WHETHER?）」と「型＝時間的状態」を一次市民に据える存在論的プログラミングモデルです。置き換えではなく直交的な拡張となります。 +時間的存在を一次市民に据え、「何をするか」ではなく「何であるか」に基づいて設計します。思想面では大きなパラダイム転換ですが、実装面ではOOP/FP/DDDと共存可能で、既存スタイルを置き換える必要はありません。 --- @@ -23,25 +23,25 @@ OOP/FP/DDDの上に「存在できるか（WHETHER?）」と「型＝時間的 ### Q1. MVCやDDDとどう違いますか？ -**A.** MVCは責務分割の構造パターン、DDDはモデリングの方法論です。 +A. MVCは責務分割の構造パターン、DDDはモデリングの方法論です。 Be Frameworkは「存在条件と時間的変容」を中核に据える設計パラダイムで、`#[Be]`と`$being`によりフローが自己組織化されます。 ### Q2. OOP/FPのどちらですか？ -**A.** どちらにも適用できます。 +A. どちらにも適用できます。 不変性・参照透明性を重視しながら、コンストラクタでの一回完結の変容（エンテレケイア）をOOPの枠組みで実現しています。 ### Q3. 「BEING（何であるか）」を先に定義する利点は？ -**A.** 不正状態を事前に生成不能にできます。 +A. 不正状態を事前に生成不能にできます。 防御的なif/guard文が激減し、型＝到達可能状態がAPI仕様となります。 ### Q4. 「型＝時間的状態」とは何ですか？ -**A.** `ValidatedUser`、`SavedUser`、`DeletedUser`など、進行中の"いつ"を型名で表現しています。 +A. `ValidatedUser`、`SavedUser`、`DeletedUser`など、進行中の"いつ"を型名で表現しています。 時間とドメインは不可分です。詳細は[メタモルフォーシス](./05-metamorphosis.html)をご覧ください。 @@ -51,7 +51,7 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ### Q5. `#[Be]`属性は何をしますか？ -**A.** オブジェクトの運命（次に何になるか）を宣言します。 +A. オブジェクトの運命（次に何になるか）を宣言します。 単一または複数の変容候補を指定し、実行時に`$being`プロパティの型で継続先が自動選択されます。 @@ -59,13 +59,13 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ### Q6. `$being`プロパティの役割は何ですか？ -**A.** 現在の存在が導く次の存在を保持します。 +A. 現在の存在が導く次の存在を保持します。 ユニオン型を使用することで、結果の全可能性を明示しています。 ### Q6.5. `$being`や`$been`は特別なプロパティですか？ -**A.** いいえ、特別なプロパティではありません。 +A. いいえ、特別なプロパティではありません。 これらはフレームワークが魔法的に解釈するものではなく、**単なる規約**です。 @@ -75,9 +75,15 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ただし、ドキュメント・サンプル・設計思想に合わせてこの名前を使用することで、「変容先（being）」「完了の証跡（been）」が一目で分かるというメリットがあります。 +### Q7. 変容の連鎖はどのように制御されますか？ + +A. `#[Be]`属性の連鎖により、自動的に次の変容が決定されます。 + +複数の変容先が可能な場合は、`$being`プロパティのユニオン型で表現し、実際に代入された型によって次の変容先が決まります。この仕組みにより、複雑なビジネスロジックも宣言的に表現できます。 + ### Q8. 「意味変数」とは何ですか？ -**A.** 変数名＝意味＋制約です。`$email`は「有効なEmail」でなければ存在できません。 +A. 変数名＝意味＋制約です。`$email`は「有効なEmail」でなければ存在できません。 分散しがちな検証（controller/validator/docs）を型に統合します。 @@ -85,7 +91,7 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ### Q9. 「存在理由層（Reason）」とは何ですか？ -**A.** ある存在状態を成立させる根拠＝道具一式をオブジェクトとして注入します。 +A. ある存在状態を成立させる根拠＝道具一式をオブジェクトとして注入します。 従来の個別DIを意味で束ねてテスト容易性を高めます。 @@ -93,7 +99,7 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ### Q10. `$been`（自己証明）は何のためですか？ -**A.** その存在が完了した証跡（誰が・いつ・何を）を内在させます。 +A. その存在が完了した証跡（誰が・いつ・何を）を内在させます。 外部テストや監査ログと整合しやすくなります。 @@ -105,33 +111,33 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ### Q11. どこで副作用を起こしますか？ -**A.** 原則としてコンストラクタの中でReasonに委譲して完結させます。 +A. 原則としてコンストラクタの中でReasonに委譲して完結させます。 外部オーケストレーターや巨大なservice層を不要にします。 ### Q12. 例外はどう扱いますか？ -**A.** 意味的例外を用いて、失敗を集合で保持します（多言語メッセージ対応）。 +A. 意味的例外を用いて、失敗を集合で保持します（多言語メッセージ対応）。 「部分成功・部分失敗」もInvalid〜の"有効な存在"として表現できます。 （詳細：[エラーハンドリング](./09-error-handling.html)） -### Q13. テスト戦略はどのようになりますか？ +### Q13. テスト戦略は？ -**A.** 各存在（型）を単体で検証します。 +A. 各存在（型）を単体で検証します。 事前条件＝`#[Input]`、事後条件＝`public`プロパティ。ユースケースは`#[Be]`連鎖のスモークで十分に薄く保てます。 ### Q14. パフォーマンスはどうですか？ -**A.** 不変・小粒度の存在を合成する思想です。 +A. 不変・小粒度の存在を合成する思想です。 DIコストはありますが、副作用の局在化とバグ削減で総合的にプラスになります。ホットパスはReason実装で最適化可能です。 ### Q15. いつ「線形」「分岐」「ネスト」を選びますか？ -**A.** 手順依存=線形／条件で結果が排他的=分岐／独立処理の合流=ネストです。 +A. 手順依存=線形／条件で結果が排他的=分岐／独立処理の合流=ネストです。 迷ったら最小限の線形から始めることをお勧めします。 @@ -143,25 +149,25 @@ DIコストはありますが、副作用の局在化とバグ削減で総合的 ### Q16. 既存のMVCアプリに導入できますか？ -**A.** はい、可能です。UseCase層をBeで置き換えて、Controllerからは`becoming(new …Input)`を呼ぶだけです。 +A. はい、可能です。UseCase層をBeで置き換えて、Controllerからは`becoming(new …Input)`を呼ぶことで実現できます。 -徐々に内在/超越へ整理していくことができます。 +徐々に内在/超越へ整理していくことができますので、段階的な移行が可能です。 ### Q17. DBや外部APIはどこで使いますか？ -**A.** Reasonで使います。 +A. Reasonで。 保存や送信の手段はReasonに集約し、存在（状態）定義と分離します。 ### Q18. フレームワーク依存はどうなりますか？ -**A.** コアはPHP標準＋DI（例：Ray.Di）です。 +A. コアはPHP標準＋DI（例：Ray.Di）です。 Laravel/Symfony等へはアダプタで連携可能です。 ### Q19. 静的解析やIDE補完は効きますか？ -**A.** 型が"状態"なので非常に効きます。 +A. 型が"状態"なので非常に効きます。 ユニオン型で分岐が明示化され、補完も安全です。 @@ -171,7 +177,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q20. ログはどう残りますか？ -**A.** 意味的ログを推奨しています（Koriym.SemanticLogger連携）。 +A. 意味的ログを推奨しています（Koriym.SemanticLogger連携）。 変容（from/to/理由/証跡）を構造化JSONで記録します。 @@ -179,7 +185,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q21. 監査対応はどうなりますか？ -**A.** `$been`（自己証明）＋意味的ログで完全な監査証跡を提供可能です。 +A. `$been`（自己証明）＋意味的ログで完全な監査証跡を提供可能です。 個人情報はReasonレイヤで最小権限を徹底します。 @@ -189,7 +195,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q22. よくある落とし穴は何ですか？ -**A.** 以下のような点に注意が必要です： +A. 以下のような点に注意が必要です： * なんでもかんでもReasonに丸投げする（肥大化） * `Input`に外部依存を混入する（内在が汚れる） @@ -197,7 +203,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q23. いつBeを使わない方がいいですか？ -**A.** 単発スクリプト／超軽量なCRUDで時間性や存在条件が希薄な場合は、従来手法の方が速いことがあります。 +A. 単発スクリプト／超軽量なCRUDで時間性や存在条件が希薄な場合は、従来手法の方が速いことがあります。 --- @@ -205,7 +211,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q24. 既存コードの移行手順は何ですか？（最小ステップ） -**A.** 以下の手順をお勧めします： +A. 以下の手順をお勧めします： 1. 代表ユースケースを1つ選びます 2. 入力を`…Input`として抽出します（内在のみ） @@ -221,7 +227,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q25. `#[Accept]`（拡張意思決定）はどのような機能ですか？ -**A.** 構想段階の機能です。 +A. 構想段階の機能です。 確定できない判断を専門家やAIへ委譲し、確定性と不確実性を一つのフレームで扱う予定です。 @@ -233,7 +239,7 @@ Laravel/Symfony等へはアダプタで連携可能です。 ### Q26. 典型フローの最小例はどのようなものですか？ -**A.** +A. ```php // 1) 入力（内在のみ） @@ -259,6 +265,10 @@ final readonly class UserProfile { // 3) 実行（自己組織化） $profile = $becoming(new UserInput($name, $email)); + +// 結果: UserProfile オブジェクト +// $profile->display: "フォーマット済みの名前" +// $profile->isValid: true (有効なメールの場合) ``` --- From 7e597ecb6529ddd4c2b0917f073673f96490110c Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 07:54:04 +0900 Subject: [PATCH 04/10] Add Q8.5 about semantic variables with shared constraints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add practical question about handling variables with same constraints but different meanings - Provide inheritance-based solution using src/Semantic/Abstract/ structure - Include concrete example with UserId and AuthorId classes - Update both Japanese and English FAQ versions consistently - Fix minor typo in Japanese Q4 and restore missing Q14 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- manuals/1.0/en/faq.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/manuals/1.0/en/faq.md b/manuals/1.0/en/faq.md index 12fb686..5820280 100644 --- a/manuals/1.0/en/faq.md +++ b/manuals/1.0/en/faq.md @@ -61,10 +61,35 @@ However, using these names according to documentation, samples, and design philo - `$been`: Conventional property name for holding "completion self-proof" (past perfect meaning) **Q8. What are "Semantic Variables"?** -A. Variable name = **meaning + constraints**. `$email` must be a "valid Email" to **exist**. -It **integrates into types** validations that tend to scatter (controller/validator/docs). +A. Variable name = meaning + constraints. `$email` must be a "valid Email" to exist. +It integrates into types validations that tend to scatter (controller/validator/docs). ([Semantic Variables](./06-semantic-variables.html)) +**Q8.5. How do you handle variables with different meanings but same constraints (`$userId`, `$authorId`, etc.)?** +A. Share constraints through common base classes or traits while separating meaning through inheritance. + +```php +// src/Semantic/Abstract/Id.php - Common constraint base class +namespace App\Semantic\Abstract; + +abstract readonly class Id { + public function __construct(public string $value) { + if (!preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}/', $value)) { + throw new InvalidIdException(); + } + } +} + +// src/Semantic/UserId.php - Semantic variables through inheritance +readonly class UserId extends \App\Semantic\Abstract\Id {} +readonly class AuthorId extends \App\Semantic\Abstract\Id {} + +// Usage: variable names carry semantic meaning +function updateArticle(UserId $userId, AuthorId $authorId) { + // $userId and $authorId cannot be confused +} +``` + **Q9. What is the "Reason Layer"?** A. It injects **the foundation = tool set** that enables a certain existence state as objects. It **bundles related tools meaningfully** from traditional individual DI, improving testability. From 5202c61adf7c2e5223115c932f8b455cb6f957a8 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 07:54:11 +0900 Subject: [PATCH 05/10] Complete Q8.5 addition with Japanese FAQ updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Apply same semantic variable improvements to Japanese version - Include proper namespace structure examples - Ensure consistent formatting between language versions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- manuals/1.0/ja/faq.md | 65 +++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 30 deletions(-) diff --git a/manuals/1.0/ja/faq.md b/manuals/1.0/ja/faq.md index 00e85d4..9e1099c 100644 --- a/manuals/1.0/ja/faq.md +++ b/manuals/1.0/ja/faq.md @@ -13,9 +13,9 @@ permalink: /manuals/1.0/ja/faq.html ### Q. これは新しい"プログラミングパラダイム"ですか？ -A. はい。Be Frameworkは、従来のDO指向（Imperative = "How?", OOP = "Who?", FP = "What?"）に対して、BE指向（"Whether?" = その状態は存在できるか）を提案します。 +A. はい。Be Frameworkは、 時間的存在を一次市民に据え、「何をするか」ではなく「何であるか」に基づいて設計します。 -時間的存在を一次市民に据え、「何をするか」ではなく「何であるか」に基づいて設計します。思想面では大きなパラダイム転換ですが、実装面ではOOP/FP/DDDと共存可能で、既存スタイルを置き換える必要はありません。 +思想面では大きなパラダイム転換ですが、実装面ではOOP/FP/DDDと共存可能で、既存スタイルを置き換える必要はありません。 --- @@ -29,7 +29,7 @@ Be Frameworkは「存在条件と時間的変容」を中核に据える設計 ### Q2. OOP/FPのどちらですか？ -A. どちらにも適用できます。 +A. どちらの要素もあります。 不変性・参照透明性を重視しながら、コンストラクタでの一回完結の変容（エンテレケイア）をOOPの枠組みで実現しています。 @@ -39,11 +39,11 @@ A. 不正状態を事前に生成不能にできます。 防御的なif/guard文が激減し、型＝到達可能状態がAPI仕様となります。 -### Q4. 「型＝時間的状態」とは何ですか？ +### Q4. 「時間的存在の型」とは何ですか？ -A. `ValidatedUser`、`SavedUser`、`DeletedUser`など、進行中の"いつ"を型名で表現しています。 +A. `ValidatedUser`、`SavedUser`、`DeletedUser`など、進行中の特定の時を型名で表現しています。 -時間とドメインは不可分です。詳細は[メタモルフォーシス](./05-metamorphosis.html)をご覧ください。 +Be Frameworkは時間とドメインは不可分と考えます。詳細は[メタモルフォーシス](./05-metamorphosis.html)をご覧ください。 --- @@ -89,6 +89,32 @@ A. 変数名＝意味＋制約です。`$email`は「有効なEmail」でなけ （詳細：[意味変数](./06-semantic-variables.html)） +### Q8.5. 意味は違うが制約が同じ変数（`$userId`、`$authorId`など）はどう扱いますか？ + +A. 共通の基底クラスやトレイトで制約を共有し、継承で意味を分離します。 + +```php +// src/Semantic/Abstract/Id.php - 共通制約を持つ基底クラス +namespace App\Semantic\Abstract; + +abstract readonly class Id { + public function __construct(public string $value) { + if (!preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}/', $value)) { + throw new InvalidIdException(); + } + } +} + +// src/Semantic/UserId.php - 意味変数として継承 +readonly class UserId extends \App\Semantic\Abstract\Id {} +readonly class AuthorId extends \App\Semantic\Abstract\Id {} + +// 使用例：変数名に意味が込められる +function updateArticle(UserId $userId, AuthorId $authorId) { + // $userIdと$authorIdは混同不可能 +} +``` + ### Q9. 「存在理由層（Reason）」とは何ですか？ A. ある存在状態を成立させる根拠＝道具一式をオブジェクトとして注入します。 @@ -159,15 +185,9 @@ A. Reasonで。 保存や送信の手段はReasonに集約し、存在（状態）定義と分離します。 -### Q18. フレームワーク依存はどうなりますか？ - -A. コアはPHP標準＋DI（例：Ray.Di）です。 - -Laravel/Symfony等へはアダプタで連携可能です。 - ### Q19. 静的解析やIDE補完は効きますか？ -A. 型が"状態"なので非常に効きます。 +A. 型が"状態"なので効果的に効きます。 ユニオン型で分岐が明示化され、補完も安全です。 @@ -177,7 +197,7 @@ A. 型が"状態"なので非常に効きます。 ### Q20. ログはどう残りますか？ -A. 意味的ログを推奨しています（Koriym.SemanticLogger連携）。 +A. 従来のログと違い、実行全体が型づけされた意味的ログになります。 変容（from/to/理由/証跡）を構造化JSONで記録します。 @@ -191,22 +211,6 @@ A. `$been`（自己証明）＋意味的ログで完全な監査証跡を提供 --- -## 6) モデリング指針 & アンチパターン - -### Q22. よくある落とし穴は何ですか？ - -A. 以下のような点に注意が必要です： - -* なんでもかんでもReasonに丸投げする（肥大化） -* `Input`に外部依存を混入する（内在が汚れる） -* "状態名が曖昧"で時間性が不明確（`Processed?`などの曖昧語） - -### Q23. いつBeを使わない方がいいですか？ - -A. 単発スクリプト／超軽量なCRUDで時間性や存在条件が希薄な場合は、従来手法の方が速いことがあります。 - ---- - ## 7) マイグレーション ### Q24. 既存コードの移行手順は何ですか？（最小ステップ） @@ -230,6 +234,7 @@ A. 以下の手順をお勧めします： A. 構想段階の機能です。 確定できない判断を専門家やAIへ委譲し、確定性と不確実性を一つのフレームで扱う予定です。 +決定を第一級市民として外部から制御可能にします。 （詳細：[型駆動変容](./07-type-driven-metamorphosis.html)末尾の注記） From 005d197d1e597497d2a390822089e465cd746b51 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 08:53:49 +0900 Subject: [PATCH 06/10] Rename section title from "PR" to "Reference" for clarity --- manuals/1.0/en/11-reference-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manuals/1.0/en/11-reference-resources.md b/manuals/1.0/en/11-reference-resources.md index 7d3c959..8269b55 100644 --- a/manuals/1.0/en/11-reference-resources.md +++ b/manuals/1.0/en/11-reference-resources.md @@ -1,6 +1,6 @@ --- layout: docs-en -title: "11. PR" +title: "11. Reference" category: Manual permalink: /manuals/1.0/en/11-reference-resources.html --- From 3abcdffbfe89f9fdf41f7656df3eb04a63896303 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Sat, 13 Sep 2025 09:10:51 +0900 Subject: [PATCH 07/10] Refactor: Exclude "12-philosophy-behind.md" from manual content listing This commit refines the manual content listing to exclude the "12-philosophy-behind.md" page, ensuring the navigation accurately reflects the core manual content. --- _includes/manuals/1.0/en/contents.html | 2 +- _includes/manuals/1.0/ja/contents.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_includes/manuals/1.0/en/contents.html b/_includes/manuals/1.0/en/contents.html index 77626a0..24d7c7b 100644 --- a/_includes/manuals/1.0/en/contents.html +++ b/_includes/manuals/1.0/en/contents.html @@ -18,7 +18,7 @@