Skip to content

Commit 3bc8d83

Browse files
committed
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. 프레이밍 추가와 어법 정리만 수행.
1 parent 1ad4df5 commit 3bc8d83

1 file changed

Lines changed: 21 additions & 8 deletions

File tree

README.md

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,15 @@
77
> **Functorium** is named from **`functor + dominium`** with a touch of **`fun`**.
88
> **dominium** is Latin for "dominion, ownership" — Domain is not just a scope, but **the problem space we own and govern**.
99
>
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.
1211
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.
1413

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.
1619
1720
## Problems to Solve
1821

@@ -22,7 +25,7 @@ Functorium is designed for .NET teams practicing enterprise DDD, teams seeking t
2225

2326
These are not simply process problems — they are **problems of design philosophy and structure**.
2427

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.**
2629

2730
| Value | Features |
2831
|-------|----------|
@@ -109,7 +112,7 @@ public sealed partial class Email : SimpleValueObject<string>
109112

110113
</details>
111114

112-
This is how AI generates exception-free, safe code structures automatically.
115+
This is how AI auto-synthesizes exception-free, safe code structures.
113116

114117
### Humans Define Rules, AI Builds Implementation, Observability Translates Back
115118

@@ -121,7 +124,11 @@ This is how AI generates exception-free, safe code structures automatically.
121124

122125
> **"Can I debug AI-written monad code at 2 AM?"**
123126
>
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**.
125132
126133
### When Requirements Change — Humans Update Text, AI Rebuilds the Implementation
127134

@@ -239,6 +246,12 @@ test-engineer : Unit/integration/architecture rule tests
239246

240247
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).
241248

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+
242255
<details>
243256
<summary><strong>Domain Model in Detail</strong> — Value Object, Entity, AggregateRoot, DomainError, Domain Event</summary>
244257

@@ -536,7 +549,7 @@ sequenceDiagram
536549
Note over OT: All three pillars share the same trace_id/request_id<br/>→ one filter correlates Logs, Metrics, and Traces
537550
```
538551

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.
540553

541554
**Traditional exception model vs. Functorium `Fin` model**:
542555

0 commit comments

Comments
 (0)