refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,243 @@
|
||||
---
|
||||
id: arch-hexagonal-clean
|
||||
title: Hexagonal / Clean Architecture — Port / Adapter / 의존 방향
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [architecture, hexagonal, clean, ddd, vibe-coding]
|
||||
tech_stack: { language: "TS", applicable_to: ["Backend"] }
|
||||
applied_in: []
|
||||
aliases: [hexagonal, ports and adapters, clean architecture, onion, dependency inversion]
|
||||
---
|
||||
|
||||
# Hexagonal / Clean Architecture
|
||||
|
||||
> **도메인 = 중심, infrastructure = 가장자리**. Port (interface) + Adapter (구현). 의존 방향 = 항상 안쪽 (도메인). 테스트 = adapter mock 으로 도메인만.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Domain: 비즈니스 로직 + entity. 외부 의존 없음.
|
||||
- Application: use case (orchestration).
|
||||
- Adapter: HTTP / DB / queue / 외부 API.
|
||||
- Port: domain ↔ adapter 사이 interface.
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### Folder
|
||||
```
|
||||
src/
|
||||
domain/ (pure)
|
||||
user.ts
|
||||
order.ts
|
||||
application/ (use case)
|
||||
createOrder.ts
|
||||
ports/ (interface)
|
||||
orderRepository.ts
|
||||
paymentGateway.ts
|
||||
adapters/ (구현)
|
||||
in/ (driving — HTTP, queue 받음)
|
||||
httpController.ts
|
||||
out/ (driven — DB, API 호출)
|
||||
pgOrderRepository.ts
|
||||
stripePaymentGateway.ts
|
||||
config.ts
|
||||
```
|
||||
|
||||
### Domain (pure)
|
||||
```ts
|
||||
// domain/order.ts
|
||||
export class Order {
|
||||
constructor(public readonly id: string, public items: Item[], public status: OrderStatus) {}
|
||||
|
||||
addItem(item: Item) {
|
||||
if (this.status !== 'open') throw new Error('order closed');
|
||||
this.items.push(item);
|
||||
}
|
||||
|
||||
total(): Decimal {
|
||||
return this.items.reduce((sum, i) => sum.add(i.price.mul(i.qty)), new Decimal(0));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
→ DB / HTTP / 시간 의존 X. 순수.
|
||||
|
||||
### Port
|
||||
```ts
|
||||
// ports/orderRepository.ts
|
||||
export interface OrderRepository {
|
||||
find(id: string): Promise<Order | null>;
|
||||
save(order: Order): Promise<void>;
|
||||
}
|
||||
|
||||
// ports/paymentGateway.ts
|
||||
export interface PaymentGateway {
|
||||
charge(amount: Decimal, currency: string): Promise<{ id: string }>;
|
||||
}
|
||||
```
|
||||
|
||||
### Application (use case)
|
||||
```ts
|
||||
// application/createOrder.ts
|
||||
export class CreateOrderUseCase {
|
||||
constructor(
|
||||
private orders: OrderRepository,
|
||||
private payment: PaymentGateway,
|
||||
) {}
|
||||
|
||||
async execute(input: CreateOrderInput): Promise<Order> {
|
||||
const order = new Order(uuid(), input.items, 'open');
|
||||
const total = order.total();
|
||||
|
||||
await this.payment.charge(total, 'USD');
|
||||
order.markPaid();
|
||||
|
||||
await this.orders.save(order);
|
||||
return order;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adapter — out (DB)
|
||||
```ts
|
||||
// adapters/out/pgOrderRepository.ts
|
||||
export class PgOrderRepository implements OrderRepository {
|
||||
constructor(private db: Drizzle) {}
|
||||
|
||||
async find(id: string): Promise<Order | null> {
|
||||
const row = await this.db.select().from(ordersTable).where(eq(ordersTable.id, id)).limit(1);
|
||||
if (!row[0]) return null;
|
||||
return toDomain(row[0]); // mapper
|
||||
}
|
||||
|
||||
async save(order: Order): Promise<void> {
|
||||
await this.db.insert(ordersTable).values(toRow(order)).onConflictDoUpdate(...);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adapter — out (External API)
|
||||
```ts
|
||||
// adapters/out/stripePaymentGateway.ts
|
||||
export class StripePaymentGateway implements PaymentGateway {
|
||||
constructor(private stripe: Stripe) {}
|
||||
|
||||
async charge(amount: Decimal, currency: string): Promise<{ id: string }> {
|
||||
const intent = await this.stripe.paymentIntents.create({
|
||||
amount: amount.mul(100).toNumber(),
|
||||
currency,
|
||||
});
|
||||
return { id: intent.id };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adapter — in (HTTP)
|
||||
```ts
|
||||
// adapters/in/httpController.ts
|
||||
export function makeOrderRouter(useCase: CreateOrderUseCase) {
|
||||
const router = express.Router();
|
||||
router.post('/orders', async (req, res) => {
|
||||
const input = CreateOrderSchema.parse(req.body);
|
||||
const order = await useCase.execute(input);
|
||||
res.json({ id: order.id, total: order.total().toString() });
|
||||
});
|
||||
return router;
|
||||
}
|
||||
```
|
||||
|
||||
### Composition root (config)
|
||||
```ts
|
||||
// config.ts — 한 곳에서 의존 주입
|
||||
const db = drizzle(new Pool(...));
|
||||
const stripe = new Stripe(...);
|
||||
|
||||
const orderRepo = new PgOrderRepository(db);
|
||||
const payment = new StripePaymentGateway(stripe);
|
||||
const createOrder = new CreateOrderUseCase(orderRepo, payment);
|
||||
|
||||
const app = express();
|
||||
app.use('/api', makeOrderRouter(createOrder));
|
||||
```
|
||||
|
||||
### Test (mock adapter)
|
||||
```ts
|
||||
class FakeOrderRepository implements OrderRepository {
|
||||
private store = new Map<string, Order>();
|
||||
async find(id: string) { return this.store.get(id) ?? null; }
|
||||
async save(o: Order) { this.store.set(o.id, o); }
|
||||
}
|
||||
|
||||
class FakePaymentGateway implements PaymentGateway {
|
||||
charges: { amount: Decimal }[] = [];
|
||||
async charge(amount: Decimal) {
|
||||
this.charges.push({ amount });
|
||||
return { id: 'fake-' + this.charges.length };
|
||||
}
|
||||
}
|
||||
|
||||
test('createOrder', async () => {
|
||||
const orders = new FakeOrderRepository();
|
||||
const payment = new FakePaymentGateway();
|
||||
const uc = new CreateOrderUseCase(orders, payment);
|
||||
|
||||
const order = await uc.execute({ items: [...] });
|
||||
expect(payment.charges).toHaveLength(1);
|
||||
expect(await orders.find(order.id)).not.toBeNull();
|
||||
});
|
||||
```
|
||||
|
||||
→ DB / Stripe 없이 빠른 unit test.
|
||||
|
||||
### 의존 방향 강제 (lint)
|
||||
```js
|
||||
// .eslintrc — dependency-cruiser 또는 import 규칙
|
||||
// domain 가 ports/adapters import 금지
|
||||
// application 이 adapters import 금지
|
||||
{
|
||||
"import/no-restricted-paths": ["error", {
|
||||
"zones": [
|
||||
{ "target": "src/domain", "from": "src/(application|adapters|ports)" },
|
||||
{ "target": "src/application", "from": "src/adapters" },
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Onion (변형)
|
||||
```
|
||||
Domain → Domain Services → Application → Infrastructure
|
||||
```
|
||||
|
||||
비슷한 의존 방향 — 이름만 다름.
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 상황 | 추천 |
|
||||
|---|---|
|
||||
| 큰 팀 / 복잡 도메인 | Hexagonal / Clean |
|
||||
| 작은 CRUD | overkill — 일반 layered |
|
||||
| 단순 script | 직접 |
|
||||
| 마이크로서비스 (작은 service) | service 안 단순 layered |
|
||||
| 큰 monolith | hexagonal 가 분리 |
|
||||
| Multiple delivery (HTTP + queue + CLI) | 매우 적합 |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Domain 안 ORM annotation**: 의존 누설.
|
||||
- **Port = repo 1:1 매핑 모든 method**: god interface. UseCase 별 작은 port.
|
||||
- **Adapter 가 도메인 직접 변형**: domain mapper 따로.
|
||||
- **DTO = Domain entity**: serialization 변경 = 도메인 변경.
|
||||
- **모든 API 가 use case**: 단순 read 도 use case — overhead. Query / Command 분리.
|
||||
- **Layer 가 너무 많음**: 5 layer cross 매번. 2-3 layer.
|
||||
- **Composition root 분산**: DI container 또는 한 곳.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- Domain (pure) → Application → Adapters 3 layer.
|
||||
- Port (interface) + Adapter 가 키워드.
|
||||
- Test = mock adapter, real domain.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[Arch_DDD_Bounded_Context]]
|
||||
- [[Arch_Aggregate_Design]]
|
||||
- [[Backend_Multi_Tenant_Architecture]]
|
||||
Reference in New Issue
Block a user