You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(readme): 페르소나·통제권 프레이밍 추가 + narrative 다듬기 (KO 일치)
README.md(영문)에 README.ko.md(커밋 1ad4df5)와 동일한 3영역 페르소나·
통제 프레이밍을 적용하여, 양 언어 문서 페어를 동일 구조로 일치시킨다.
피드백의 인지적 부조화 문제는 영문 README에도 동일하게 적용된다:
"비즈니스 규칙만 텍스트로 정의하세요 — AI가 파이프라인을 생성합니다"
라는 첫 약속과, 본문 절반이 모나드·CQRS·Observable Port 내부 동작을
설명하는 것 사이의 충돌이다. 맥락이 없으면 독자는 자율주행차를 사고
조수석 서랍에서 100페이지 피스톤 정비 매뉴얼을 발견한 격이 된다.
해결책은 처음부터 페르소나를 못 박고, 깊은 아키텍처를 "AI 통제용
무기"로 재프레이밍하는 것.
3개 프레이밍 박스 추가 (한글판과 라인 번호 완전 일치):
1. 영역 A — 페르소나 (라인 14)
"도메인 규칙만 던져주면 되는 기획자/주니어 개발자용이 아닙니다.
AI 산출물의 무결성을 직접 검토·통제하고, 시스템 경계와 아키텍처를
설정해야 하는 애플리케이션 아키텍트용 심층 가이드."
2. 영역 B — 통제권 프레이밍 (라인 129, "새벽 2시" 인용 박스 직후)
"AI가 짠다고 해서, 사람이 이해하지 않아도 되는 것은 아닙니다.
이어지는 모나드·CQRS·Observable Port 설명은 짊어져야 할 짐이
아니라 AI를 통제하기 위해 손에 쥐어야 하는 무기."
3. 영역 C — 깊은 섹션 진입 안내 (라인 249, "Functional Architecture
in Detail" 섹션 도입부)
"이 섹션부터는 통제용 자료. 단순 사용자는 Getting Started로
건너뛰어도 OK — 패키지 설치만으로 첫 코드 실행 가능."
Narrative 정리 (5건):
- "The result compiles into" → "The output compiles directly into"
- "makes these decisions once, consistently" → "makes all these
decisions in one place"
- "AI generates exception-free, safe code structures automatically"
→ "AI auto-synthesizes exception-free, safe code structures"
- "translate code state into human language" → "translate the
AI-generated pipeline's internal state into diagnostics a human
can read instantly"
- 3-Pillar 강조 문장: "no logging or metric code by hand" →
"zero logging or metric code by hand"
본문 길이 변화: 676 → 688줄 (+12, 한글판 1ad4df57과 동일 delta).
정보 추가/삭제 0. 프레이밍 추가와 어법 정리만 수행.
Copy file name to clipboardExpand all lines: README.md
+21-8Lines changed: 21 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,12 +7,15 @@
7
7
> **Functorium** is named from **`functor + dominium`** with a touch of **`fun`**.
8
8
> **dominium** is Latin for "dominion, ownership" — Domain is not just a scope, but **the problem space we own and govern**.
9
9
>
10
-
> Functorium is an **AI Native .NET framework** where AI agents directly guide domain design and generate code.
11
-
> The result compiles into production code with functional architecture + DDD + Observability built in.
10
+
> Functorium is an **AI Native .NET framework** where AI agents directly guide domain design and generate code. The output compiles directly into production code with functional architecture + DDD + Observability built in.
12
11
13
-
**6 specialist AI agents** guide a 7-step workflow from requirements analysis to testing. At each step, design documents and compilable C# code are generated simultaneously. No need to manually make hundreds of architecture decisions.
12
+
**6 specialist AI agents** guide a 7-step workflow from requirements analysis to testing. At each step, design documents and compilable C# code are generated simultaneously, so there is no need to make hundreds of architecture decisions by hand.
14
13
15
-
Functorium is designed for .NET teams practicing enterprise DDD, teams seeking to bridge the language gap between development and operations, and architects systematically adopting functional DDD architecture.
14
+
> **Who is this document for?**
15
+
>
16
+
> Not for product managers or junior developers who only hand off domain rules. This is an in-depth guide for **application architects** who must directly review and govern the integrity of AI-generated artifacts and set the boundaries and architecture of the system.
17
+
>
18
+
> AI auto-synthesizes the pipeline. But **defining what should be synthesized** and **judging whether the synthesized result can be trusted** remain human responsibilities. That is why this document goes the full distance, all the way down to the inner mechanics of monads, CQRS, and Observable Port.
16
19
17
20
## Problems to Solve
18
21
@@ -22,7 +25,7 @@ Functorium is designed for .NET teams practicing enterprise DDD, teams seeking t
22
25
23
26
These are not simply process problems — they are **problems of design philosophy and structure**.
24
27
25
-
Mediator, LanguageExt, FluentValidation, and OpenTelemetry are each excellent. But integrating them into a coherent DDD architecture requires hundreds of decisions about error propagation, pipeline ordering, observability boundaries, and type constraints. Functorium makes these decisions once, consistently — and **AI agents automatically apply these decisions to your project.**
28
+
Mediator, LanguageExt, FluentValidation, and OpenTelemetry are each excellent. But integrating them into a coherent DDD architecture requires hundreds of decisions about error propagation, pipeline ordering, observability boundaries, and type constraints. Functorium makes all these decisions in one place — and **AI agents automatically apply them to your project.**
26
29
27
30
| Value | Features |
28
31
|-------|----------|
@@ -109,7 +112,7 @@ public sealed partial class Email : SimpleValueObject<string>
109
112
110
113
</details>
111
114
112
-
This is how AI generates exception-free, safe code structures automatically.
115
+
This is how AI auto-synthesizes exception-free, safe code structures.
113
116
114
117
### Humans Define Rules, AI Builds Implementation, Observability Translates Back
115
118
@@ -121,7 +124,11 @@ This is how AI generates exception-free, safe code structures automatically.
121
124
122
125
> **"Can I debug AI-written monad code at 2 AM?"**
123
126
>
124
-
> The framework's **automatic error classification + structured context logs + dashboards** — built into every Command/Query — translate code state into human language.
127
+
> The framework's **automatic error classification + structured context logs + dashboards** — built into every Command/Query — translate the AI-generated pipeline's internal state into diagnostics a human can read instantly.
128
+
129
+
> **AI writing the code does not exempt humans from understanding it.**
130
+
>
131
+
> AI writes the code, but reviewing the integrity of the result and tuning it to business requirements ultimately falls to the **human architect.** That is why the monad, CQRS, and Observable Port internals this document goes on to explain are **not a burden you must shoulder — they are the weapons you need in hand to govern the AI**.
125
132
126
133
### When Requirements Change — Humans Update Text, AI Rebuilds the Implementation
Building on the Email implementation above, let's explore additional framework patterns. For CQRS Command/Query usecase implementation examples, see the [CQRS Repository Tutorial](./Docs.Site/src/content/docs/tutorials/cqrs-repository/index.md).
241
248
249
+
> **From here on, this is governance material.**
250
+
>
251
+
> Going through Domain Model → CQRS → Observability in order, this section covers the internal mechanics an architect must hold in hand to **govern, modify, and extend** AI-generated code. It fills in, in one pass, the vocabulary needed to judge **on what basis to trust** AI artifacts at each layer.
252
+
>
253
+
> If you are a casual user, skip ahead to [Getting Started](#getting-started) — package install alone is enough to run your first code. This section is for those who carry responsibility for the system.
254
+
242
255
<details>
243
256
<summary><strong>Domain Model in Detail</strong> — Value Object, Entity, AggregateRoot, DomainError, Domain Event</summary>
244
257
@@ -536,7 +549,7 @@ sequenceDiagram
536
549
Note over OT: All three pillars share the same trace_id/request_id<br/>→ one filter correlates Logs, Metrics, and Traces
537
550
```
538
551
539
-
The three pillars (Logs, Metrics, Traces) shown above are emitted **automatically** by Source Generators and the Usecase Pipeline — developers write no logging or metric code by hand.
552
+
The three pillars (Logs, Metrics, Traces) shown above are emitted **automatically** by Source Generators and the Usecase Pipeline — developers write zero logging or metric code by hand.
540
553
541
554
**Traditional exception model vs. Functorium `Fin` model**:
0 commit comments