오늘도 공부

RAG 다음 단계: LLM Wiki

행복한 수지아빠 — Thu, 27 Aug 2026 16:04:30 +0900

LLM을 개인 지식관리나 리서치에 활용할 때 가장 흔한 구조는 RAG(Retrieval-Augmented Generation)다.

문서들을 저장해 두고, 사용자가 질문하면 관련 문서 조각을 검색한 뒤 LLM에게 전달한다.

Documents
   ↓
Chunking
   ↓
Embedding / Index
   ↓
Retrieval
   ↓
LLM
   ↓
Answer

이 방식은 효율적이다.

하지만 한 가지 구조적인 문제가 있다.

매번 지식을 다시 조립해야 한다.

100개의 문서를 읽고 5개의 자료를 연결해 어떤 결론을 만들었다고 하더라도, 다음 질문에서는 다시 검색하고 다시 조합해야 한다.

LLM 입장에서는 이전에 수행했던 분석이 하나의 지식 구조로 축적되지 않는다.

Karpathy가 공개한 LLM Wiki 아이디어는 바로 이 문제를 다르게 접근한다.

핵심은 단순하다.

원본 문서를 검색하는 것에 그치지 않고, LLM이 지속적으로 관리하는 Markdown Wiki를 중간 계층에 둔다.

즉,

Raw Sources
      ↓
     LLM
      ↓
Persistent Wiki
      ↓
     Query

라는 구조다.

이 Wiki는 단순한 요약 저장소가 아니다.

새로운 자료가 들어올 때마다 기존 지식과 비교하고, 관련 문서를 업데이트하고, 모순을 기록하고, 새로운 연결을 만들어내는 지속적으로 진화하는 지식베이스다.

1. RAG와 LLM Wiki의 가장 큰 차이

일반적인 RAG에서는 원본 자료가 지식의 중심이다.

질문
 ↓
원본 문서 검색
 ↓
관련 Chunk 추출
 ↓
LLM이 즉석에서 종합
 ↓
답변

예를 들어 AI Agent에 대해 100개의 글을 저장했다고 하자.

사용자가 다음 질문을 한다.

MCP와 Agent Skill은 어떤 관계인가?

RAG 시스템에서는 매번 MCP와 Agent Skill 관련 문서를 검색하고 LLM이 새롭게 관계를 정리한다.

반면 LLM Wiki에서는 이미 다음과 같은 페이지가 존재할 수 있다.

wiki/
├── ai-agent.md
├── mcp.md
├── agent-skill.md
├── tool-use.md
├── context-engineering.md
└── agent-architecture.md

그리고 각 문서는 서로 연결된다.

# MCP

MCP는 LLM Agent가 외부 도구와 데이터를
표준화된 방식으로 연결하기 위한 프로토콜이다.

관련 개념:

- [Agent Skill](agent-skill.md)
- [Tool Use](tool-use.md)
- [Context Engineering](context-engineering.md)

새로운 MCP 관련 글이 들어오면 LLM은 단순히 source-103.md를 추가하는 것으로 끝내지 않는다.

기존의

mcp.md
agent-skill.md
tool-use.md
agent-architecture.md

등을 함께 수정할 수 있다.

즉 지식이 누적된다.

2. 이 구조는 사실상 ‘지식 컴파일’에 가깝다

이 구조를 개발 관점에서 보면 재미있는 비유가 가능하다.

Raw Source를 소스 코드라고 생각해보자.

Raw Sources
   =
Source Code

LLM은 컴파일러 역할을 한다.

LLM
 =
Compiler

그리고 Wiki는 컴파일된 지식이다.

Wiki
 =
Compiled Knowledge

전체 흐름은 다음과 같다.

Articles
Papers
Videos
Meetings
Documents
     │
     ▼
┌───────────────┐
│      LLM      │
│ Knowledge     │
│ Compiler      │
└───────────────┘
     │
     ▼
┌────────────────────┐
│ Persistent Wiki    │
│                    │
│ Concepts           │
│ Entities           │
│ Comparisons        │
│ Relationships      │
│ Synthesis          │
└────────────────────┘

RAG가 필요할 때마다 지식을 해석하는 인터프리터형 접근이라면,

LLM Wiki는 미리 지식을 구조화하는 컴파일형 접근이라고 볼 수 있다.

물론 실제 컴파일러와 동일한 개념은 아니다.

하지만 시스템 설계 관점에서는 꽤 유용한 모델이다.

3. 시스템은 세 개의 계층으로 구성된다

LLM Wiki의 기본 구조에는 세 가지 핵심 레이어가 있다.

① Raw Sources

사용자가 수집한 원본 자료다.

예를 들면:

raw/
├── article-openai-agents.md
├── anthropic-agent-skills.md
├── mcp-spec.md
├── paper-context-engineering.pdf
└── assets/

여기에서 중요한 원칙이 있다.

LLM은 Raw Source를 수정하지 않는다.

원본 자료는 Source of Truth 역할을 한다.

raw = immutable

잘못된 요약이나 해석이 생겨도 원본을 다시 확인할 수 있기 때문이다.

4. 두 번째 계층은 LLM이 관리하는 Wiki다

Wiki는 사람이 직접 작성하는 공간이라기보다는 LLM이 유지보수하는 코드베이스에 가깝다.

예를 들어 다음과 같은 구조가 만들어질 수 있다.

wiki/
├── README.md
│
├── concepts/
│   ├── ai-agent.md
│   ├── context-engineering.md
│   ├── rag.md
│   └── agent-memory.md
│
├── technologies/
│   ├── mcp.md
│   ├── agent-skills.md
│   └── vector-database.md
│
├── companies/
│   ├── openai.md
│   ├── anthropic.md
│   └── google.md
│
└── comparisons/
    └── rag-vs-llm-wiki.md

LLM이 담당하는 작업은 상당히 많다.

새로운 자료를 읽으면 다음 작업을 수행한다.

요약
↓
개념 추출
↓
관련 페이지 탐색
↓
기존 주장과 비교
↓
페이지 수정
↓
Cross-reference 생성
↓
README 업데이트
↓
Git commit

하나의 자료가 들어오면서 10~15개의 문서가 동시에 수정될 수도 있다.

일반적인 개인 Wiki에서는 이런 유지보수가 가장 큰 부담이다.

LLM Wiki에서는 이 유지보수 자체를 Agent에게 맡긴다.

5. 세 번째 계층: AGENTS.md

실제로 가장 중요한 파일은 Wiki가 아닐 수도 있다.

Agent에게 지식베이스 관리 규칙을 알려주는 파일이다.

Codex라면:

AGENTS.md

Claude Code라면:

CLAUDE.md

형태로 둘 수 있다.

이 파일은 일종의 Knowledge Base Constitution 역할을 한다.

예를 들어 다음과 같은 규칙을 정의할 수 있다.

# Wiki Rules

## Source Rules

- raw/ 파일은 절대 수정하지 않는다.
- 모든 중요한 주장에는 Source를 연결한다.
- Source 없는 추론은 명시적으로 표시한다.

## Page Rules

각 페이지는 다음 구조를 사용한다.

1. Summary
2. Key Concepts
3. Relationships
4. Evidence
5. Open Questions
6. Sources

## Link Rules

Wikilink를 사용하지 않는다.

잘못된 예:

[[MCP]]

올바른 예:

[MCP](mcp.md)

## Update Rules

새로운 Source가 기존 주장과 충돌하면
기존 내용을 삭제하지 말고 contradiction을 기록한다.

이 파일의 품질에 따라 Wiki의 품질도 크게 달라질 수 있다.

결국 LLM Wiki 구축에서 중요한 것은 단순한 Prompt Engineering보다 Knowledge Governance다.

6. 가장 중요한 Operation: Ingest

새로운 자료가 들어오면 Agent는 단순 요약보다 더 많은 작업을 한다.

예를 들어 다음 자료가 추가됐다고 하자.

raw/anthropic-agent-skills-2026.md

Agent가 수행하는 흐름은 다음과 같다.

Source 읽기
     ↓
핵심 주장 추출
     ↓
기존 Wiki 검색
     ↓
관련 개념 찾기
     ↓
기존 주장과 비교
     ↓
새 페이지 생성 또는 기존 페이지 수정
     ↓
Cross-reference 업데이트
     ↓
README 업데이트
     ↓
Git Commit

Git commit은 예를 들어 다음과 같이 만들 수 있다.

ingest: Anthropic Agent Skills architecture

- added agent-skills.md
- updated ai-agent.md
- updated mcp.md
- added skill-vs-tool comparison
- linked Anthropic architecture sources

이 Commit 자체가 지식베이스의 변경 기록이 된다.

7. log.md보다 Git History

초기 아이디어에서는 Wiki 변경 기록을

log.md

에 저장하는 방법이 제안됐다.

하지만 이후 버전에서는 Git 자체를 로그 시스템으로 사용하는 쪽으로 개선됐다.

그 이유는 명확하다.

여러 Agent가 동시에 작업하면 append-only 파일은 충돌하기 쉽다.

Agent A → log.md 마지막 줄 수정
Agent B → log.md 마지막 줄 수정

→ Merge Conflict

Git은 이미 변경 이력을 관리하기 위한 시스템이다.

따라서

git log --oneline -- wiki/

만 실행해도 Wiki의 전체 변화 과정을 확인할 수 있다.

특정 페이지 변화는

git log --follow -p wiki/mcp.md

로 추적할 수 있다.

이 설계는 꽤 중요하다.

별도의 지식 History 시스템을 만드는 대신 Git 자체를 Temporal Memory로 활용한다.

8. README.md는 Wiki의 Router 역할을 한다

Wiki가 커지면 Agent가 매번 모든 Markdown 파일을 읽을 수 없다.

따라서 Root에

README.md

를 둔다.

예를 들어:

# AI Engineering Wiki

## Agent Architecture

- [AI Agent](concepts/ai-agent.md)
  Agent architecture overview

- [Agent Memory](concepts/agent-memory.md)
  Persistent and temporary memory mechanisms

## Protocols

- [MCP](technologies/mcp.md)
  Model Context Protocol

## Retrieval

- [RAG](concepts/rag.md)
  Retrieval Augmented Generation

질문이 들어오면 Agent는 먼저 README를 읽는다.

Question
   ↓
README
   ↓
Relevant Pages
   ↓
Sources

이렇게 하면 수백 페이지 정도까지는 Vector DB 없이도 꽤 효율적인 탐색이 가능하다.

README는 사실상 LLM용 Knowledge Router 역할을 한다.

9. Wiki가 커지면 계층 구조를 만든다

처음부터 복잡한 디렉터리를 만드는 것은 권장되지 않는다.

초기에는 다음처럼 Flat 구조로 시작한다.

wiki/
├── README.md
├── mcp.md
├── rag.md
├── agent.md
├── context-engineering.md
└── agent-memory.md

페이지가 늘어나면서 자연스럽게 Cluster가 생긴다.

예:

agent.md
agent-memory.md
agent-tools.md
agent-planning.md
agent-evaluation.md

이 시점에 Agent가 다음 구조를 제안할 수 있다.

wiki/
└── agents/
    ├── README.md
    ├── architecture.md
    ├── memory.md
    ├── tools.md
    ├── planning.md
    └── evaluation.md

즉 Wiki 구조 변경 자체도 Agent가 관리한다.

이 작업을 원문에서는 Codebase의 Refactoring / Compaction과 유사하게 본다.

10. Wiki에도 기술 부채가 생긴다

지식베이스 역시 시간이 지나면 기술 부채와 비슷한 문제가 발생한다.

예를 들어:

중복 페이지
오래된 주장
서로 충돌하는 설명
고립된 페이지
너무 긴 문서
잘못된 분류
깨진 링크

따라서 LLM Wiki에서는 두 가지 유지보수 작업이 중요하다.

Lint

문제를 탐지한다.

contradiction
stale claim
orphan page
missing link
missing concept
source gap

Compact

문제를 실제로 수정한다.

merge
rewrite
split
delete
move
restructure

개발에 대응시키면 다음과 같다.

Wiki Lint
≈
Static Analysis

Wiki Compact
≈
Refactoring

상당히 개발자 친화적인 Knowledge Management 모델이다.

11. 질문 역시 지식이 된다

이 시스템의 중요한 특징 중 하나는 Query 결과도 Wiki에 다시 저장할 수 있다는 것이다.

예를 들어 사용자가 묻는다.

MCP와 Agent Skill 중 어느 것을 먼저 도입해야 하는가?

Agent가 기존 자료를 분석해 비교 문서를 만든다.

comparisons/
└── mcp-vs-agent-skills.md

다음 질문에서는 이 분석을 다시 처음부터 하지 않아도 된다.

Source
   ↓
Wiki

Question
   ↓
Analysis
   ↓
Wiki

Question
   ↓
Analysis
   ↓
Wiki

따라서 Source뿐 아니라 사고 과정에서 만들어낸 분석 결과 자체도 Knowledge Asset으로 축적된다.

이 부분이 일반적인 Chat History와 가장 큰 차이다.

12. 검색은 처음부터 Vector DB가 필요하지 않다

많은 개발자는 지식베이스라고 하면 바로 다음 스택을 떠올린다.

Embedding
Vector DB
Hybrid Search
Reranker
RAG Pipeline

하지만 LLM Wiki에서는 처음부터 이런 인프라가 필요하지 않을 수 있다.

초기에는

README
grep
ripgrep
find

정도로 충분하다.

예:

rg "MCP" wiki/

또는 Markdown 전용 Local Search Tool을 사용할 수도 있다.

원문에서는 qmd 같은 도구가 예로 언급된다.

Wiki가 커지면 다음 단계로 발전시킬 수 있다.

Stage 1

README + grep


Stage 2

BM25 search


Stage 3

BM25 + Vector Search


Stage 4

Hybrid Search + Reranker

즉 검색 인프라를 처음부터 과도하게 구축할 필요가 없다.

13. Git + Markdown이 중요한 이유

이 구조에서 Markdown과 Git은 우연한 선택이 아니다.

Markdown은:

LLM이 읽기 쉽다
LLM이 수정하기 쉽다
diff 확인이 쉽다
Git과 궁합이 좋다
Obsidian/GitHub에서 바로 렌더링된다

Git은:

Versioning
Diff
Rollback
Branch
Merge
History
Collaboration

을 제공한다.

따라서 별도의 Knowledge Management Database가 없어도 상당히 강력한 시스템을 만들 수 있다.

14. Obsidian의 역할

이 구조에서 Obsidian은 지식을 만드는 시스템이라기보다 Knowledge IDE에 가깝다.

원문의 표현을 개발자 관점으로 정리하면 다음과 같다.

Obsidian
=
IDE

LLM Agent
=
Programmer

Wiki
=
Codebase

Raw Sources
=
Input Data

AGENTS.md
=
Coding Rules

Git
=
Version Control

특히 Obsidian Graph View를 이용하면

Concept
 ↔
Entity
 ↔
Source
 ↔
Analysis

관계를 시각적으로 확인할 수 있다.

15. 실제로 구현한다면

가장 단순한 MVP는 다음 정도로 충분하다.

knowledge/
│
├── AGENTS.md
│
├── raw/
│   ├── source-001.md
│   ├── source-002.md
│   └── assets/
│
└── wiki/
    ├── README.md
    ├── mcp.md
    ├── rag.md
    └── agent-memory.md

Agent에게 다음 네 가지 Command만 정의해도 된다.

/ingest
/query
/lint
/compact

/ingest

새 Source 분석
→ Wiki 업데이트
→ Cross-reference
→ README 수정
→ Commit

/query

README 탐색
→ 관련 Wiki 탐색
→ 필요 시 Raw Source 확인
→ 답변 생성
→ 가치 있는 분석이면 Wiki 저장

/lint

중복
모순
오래된 주장
고립 페이지
깨진 링크
Source 부족
검사

/compact

중복 페이지 Merge
긴 페이지 Split
Directory 재구성
Stale 정보 제거
Cross-reference 수정

이 정도만으로도 상당히 강력한 개인 지식 시스템을 만들 수 있다.

16. 더 발전시키면 Agentic Knowledge Pipeline이 된다

이 구조를 자동화하면 다음 형태까지 발전할 수 있다.

Web
RSS
GitHub
YouTube
Papers
Slack
Meetings
   │
   ▼
Source Collector
   │
   ▼
raw/
   │
   ▼
Ingest Agent
   │
   ├─ Entity Extraction
   ├─ Concept Extraction
   ├─ Contradiction Detection
   ├─ Relationship Discovery
   └─ Source Verification
   │
   ▼
Wiki
   │
   ├─ README
   ├─ Concepts
   ├─ Entities
   ├─ Comparisons
   └─ Synthesis
   │
   ▼
Git

여기에 Scheduler를 붙이면 주기적으로

lint
compact
link check
stale claim check

를 실행할 수 있다.

결국 단순한 Wiki가 아니라 Agent가 유지보수하는 지식 운영 시스템이 된다.

17. RAG를 없애자는 아이디어는 아니다

중요한 점이 하나 있다.

LLM Wiki와 RAG는 경쟁 관계일 필요가 없다.

오히려 두 구조를 조합하는 것이 자연스럽다.

               ┌─ Wiki Search
Question ──────┤
               └─ Raw Source RAG
                       │
                       ▼
                      LLM

Wiki에는 이미 정리된 지식이 들어 있고,

Raw Source RAG는 다음 용도로 사용한다.

원문 검증
정확한 인용
세부 데이터 확인
새로운 정보 탐색

따라서 현실적인 구조는

Wiki + RAG

가 될 가능성이 높다.

Wiki가 Semantic Memory라면 Raw Source는 Evidence Store에 가까운 역할을 한다.

18. 이 아이디어의 진짜 핵심

표면적으로 보면 이 시스템은 단순하다.

Markdown
+
Git
+
LLM

뿐이다.

하지만 중요한 것은 저장 기술이 아니다.

기존 RAG에서는

Knowledge = Documents

였다.

LLM Wiki에서는

Knowledge =
Documents
+
Relationships
+
Synthesis
+
History
+
Questions
+
Analysis

가 된다.

즉 지식의 단위를 문서에서 지속적으로 업데이트되는 지식 구조로 바꾸는 것이다.

그래서 이 시스템의 핵심은 Wiki 자체라기보다 다음 개념에 있다.

LLM이 지식을 소비하는 Agent에서 지식을 지속적으로 유지보수하는 Agent로 바뀐다.

결론

LLM 시대의 개인 지식관리 시스템을 단순히

문서 저장
→ Embedding
→ Vector Search
→ 답변

으로만 생각할 필요는 없다.

한 단계 더 나아가면

Source
   ↓
LLM
   ↓
Structured Knowledge
   ↓
Continuous Maintenance
   ↓
Git History
   ↓
Accumulated Intelligence

구조를 만들 수 있다.

특히 Codex, Claude Code 같은 Coding Agent가 등장하면서 이 방식은 구현하기 훨씬 쉬워졌다.

Markdown Wiki는 일종의 코드베이스가 되고,

LLM Agent는 그 코드베이스를 관리하는 개발자가 된다.

그리고 인간은 직접 Wiki를 정리하는 대신,

좋은 자료를 찾고
좋은 질문을 하고
중요한 방향을 결정하는 것

에 집중한다.

결국 이 아이디어의 가장 흥미로운 지점은 LLM에게 더 많은 문서를 검색하게 하는 것이 아니라, 한 번 이해한 지식을 다시 잃어버리지 않게 만드는 것이다.

RAG가 LLM에게 외부 기억을 제공했다면,

LLM Wiki는 그 기억을 시간이 지날수록 구조화하고 축적하는 방법에 더 가깝다.

Grok Bot과 Kimi K3로 배우는 Graph & Loop Engineering

행복한 수지아빠 — Thu, 27 Aug 2026 12:37:16 +0900

AI 에이전트 시스템의 문제는 모델 성능만으로 해결되지 않는다.

실제 운영 환경에서 더 자주 문제가 되는 것은 다음 세 가지다.

작업이 실패했을 때 누가 다시 시작할 것인가
여러 에이전트가 사용하는 공유 상태를 어디에 저장할 것인가
실제 외부 시스템을 변경하기 전에 누가 승인할 것인가

에이전트를 여러 개 붙여 놓는다고 안정적인 시스템이 만들어지는 것은 아니다.

필요한 것은 에이전트 군집(Swarm) 자체가 아니라, 에이전트가 어떤 작업을 수행해야 하는지 판단하고 결과를 검증하며 다시 작업으로 되돌리는 제어 시스템(Control System) 이다.

이 글에서는 다음과 같은 구조를 사용한다.

Grok Bot
   │
   │ Outer Loop
   ▼
Coordinator
   │
   ├── Knowledge Graph
   ├── DAG
   ├── Context Pack
   ├── Policy / Approval
   └── Append Log
            │
            ▼
        Kimi Code
            │
            ▼
            K3
       Agent / Swarm

핵심 역할은 다음과 같다.

Grok Bot

전체 실행 흐름인 Outer Loop를 관리한다.

Kimi Code + K3

한 번의 제한된 작업 Round에서 분석, 코딩, 조사 같은 깊은 작업을 수행한다.

Knowledge Graph

출처를 가진 장기 지식을 저장한다.

DAG

어떤 작업을 어떤 순서로 실행할지 정의한다.

Context Pack

각 에이전트에게 전달되는 컨텍스트를 제한한다.

Policy Layer

도구와 외부 작업에 대한 권한을 통제한다.

Append Log

모든 상태 전환과 실행 이력을 기록한다.

이 구조를 이해하면 단순한 AI Agent를 넘어 장기간 반복해서 운영할 수 있는 Agent Harness를 설계할 수 있다.

1. Loop Engineering

"계속해"는 Loop가 아니다

LLM에게 다음과 같이 지시한다고 생각해 보자.

문제가 해결될 때까지 계속 작업해.

이것은 제대로 된 Loop가 아니다.

신뢰할 수 있는 Loop에는 최소한 네 가지 요소가 필요하다.

Owner
Worker
Verifier
Stop Rule

예를 들어 다음 구조다.

Coordinator
     │
     ▼
 Worker
     │
     ▼
Verifier
     │
 ┌───┴────┐
PASS    REVISE
 │         │
END        └──── Worker

Coordinator는 전체 작업을 소유한다.

Worker는 하나의 후보 결과를 만든다.

Verifier는 미리 정의된 Acceptance Test를 검사한다.

실패하면 전체 작업을 처음부터 다시 설명하지 않는다.

Verifier가 실패시킨 조건만 Worker에게 다시 전달한다.

2. 가장 단순한 3-Agent Loop

처음부터 수십 개의 Agent를 만들 필요는 없다.

다음 세 개부터 시작하는 것이 좋다.

Coordinator
Worker
Verifier

Coordinator의 기본 동작은 다음과 같다.

1. source event로부터 stable job_id 생성

2. Worker에게 candidate 생성 요청

3. Verifier가
   PASS
   REVISE
   BLOCKED
   중 하나를 반환

4. REVISE이면
   실패한 테스트만 Worker에게 전달

5. 최대 3 Round 실행

6. 동일한 결과가 반복되면 중단

7. 필요한 Source가 없거나 오래됐으면 중단

8. 외부 작업은 Draft 상태 유지

9. 실제 실행 전
   target + payload를 사용자에게 표시

10. 모든 handoff를 append log에 기록

여기에서 매우 중요한 개념이 하나 있다.

Round와 Retry는 다르다

API timeout이 발생했다고 새로운 Round가 되어서는 안 된다.

Round 1
   │
   ├─ attempt 1 → timeout
   ├─ attempt 2 → rate limit
   └─ attempt 3 → success

이것은 여전히 Round 1이다.

새로운 Round는 Verifier가 새로운 정보를 생성했을 때만 시작한다.

Round 1
Worker
 ↓
Verifier
 ↓
Failed Check

Round 2
Worker

3. Kimi K3를 Inner Worker로 사용하기

전체 시스템의 제어권을 Kimi에게 주는 방식보다는 Kimi가 한 번의 제한된 작업만 수행하도록 만드는 것이 핵심이다.

개념적으로 다음과 같다.

Grok Coordinator

     ↓ task.json

Kimi K3
"한 번만 작업"

     ↓ candidate.json

Grok Verifier

Kimi Worker는 다음 정도의 책임만 가진다.

입력 읽기
↓
분석
↓
필요한 경우 Sub-Agent 사용
↓
Candidate 생성
↓
종료

외부 시스템 변경은 하지 않는다.

4. Worker Output을 Contract로 만든다

Agent의 결과를 자연어만으로 전달하면 자동화하기 어렵다.

따라서 Output Contract를 정의한다.

예를 들어:

{
  "job_id": "demo-001",
  "round": 1,
  "status": "CANDIDATE",
  "summary": "...",
  "evidence": [],
  "failed_checks": [],
  "next_step": "...",
  "requires_human_approval": false
}

중요한 것은 결과를 받은 이후다.

Bridge가 반드시 다음 작업을 수행한다.

LLM Output
    ↓
JSON Parse
    ↓
Schema Validation
    ↓
Canonical JSON
    ↓
SHA-256
    ↓
candidate.json

LLM이 직접 fingerprint를 계산하게 하지 않는 것이 좋다.

시스템이 동일한 방식으로 계산해야 한다.

5. Output Fingerprint

Agent Loop에서 자주 발생하는 문제 중 하나가 같은 답을 조금씩 표현만 바꾸며 반복하는 현상이다.

이를 감지하기 위해 결과를 fingerprint한다.

예를 들어 다음 데이터가 있다.

{
  "status": "CANDIDATE",
  "summary": "...",
  "evidence": [],
  "failed_checks": []
}

이 semantic payload를 canonical JSON으로 만든다.

canonical JSON
      ↓
SHA-256
      ↓
output_fingerprint

그리고 이전 Round와 비교한다.

Round 1
fingerprint = abc123

Round 2
fingerprint = abc123

동일하다면:

NO_PROGRESS

로 중단한다.

이것이 무한 Loop를 막는 중요한 Stop Rule이다.

6. Idempotency

자동화 Agent가 가장 위험한 순간은 외부 작업을 수행할 때다.

예를 들어:

이메일 발송
결제
SNS 게시
파일 삭제
Production Deploy
계정 권한 변경

네트워크 timeout이 발생하면 Agent는 다음과 같은 상황을 알 수 없다.

요청 실패

인지

실제로는 성공했지만
응답만 받지 못함

인지 알 수 없다.

그래서 Idempotency Key가 필요하다.

Round용 Key:

job_id + round + input_sha256

실제 외부 작업용 Key:

job_id + ":commit"

예:

job_483:commit

7. External Effect의 안전한 실행

실제 외부 작업은 다음 순서로 처리한다.

Approval
   ↓
Claim idempotency key
   ↓
Execute
   ↓
Verify Live State
   ↓
Store Receipt
   ↓
Completion Marker

완료 여부를 먼저 기록하면 안 된다.

반드시 실제 시스템 상태를 확인한 다음 기록해야 한다.

예를 들어 이메일이라면:

send()
 ↓
provider receipt 확인
 ↓
message ID 저장
 ↓
completed

8. 자동 Loop Controller

전체 흐름을 의사 코드로 만들면 다음과 비슷하다.

job_id = stable_id(source_event)

if completion_marker exists:
    return DUPLICATE

effect = read_effect(job_id + ":commit")

if effect == CLAIMED:
    reconcile live state

for round in 1..3:

    write task.json

    run Kimi

    validate result

    fingerprint =
        sha256(canonical_payload)

    append event log

    verdict =
        Grok verifier(result)

    if verdict == PASS:

        if external effect 없음:
            complete
            stop

        else:
            request approval

            claim idempotency key

            execute

            verify live state

            save receipt

            complete

            stop

    if verdict == BLOCKED:
        stop

    if fingerprint ==
       previous_fingerprint:

        stop NO_PROGRESS

    send failed checks
    to next round

stop MAX_ROUNDS

이것이 Loop Engineering의 핵심이다.

9. Graph Engineering

여기서 중요한 구분이 있다.

Agent 시스템에서 흔히 "Graph"라고 부르는 것은 사실 두 종류다.

Knowledge Graph
Execution Graph

둘은 완전히 다른 역할을 한다.

10. Knowledge Graph

Knowledge Graph는 시스템이 장기간 기억해야 할 사실을 저장한다.

예:

Kimi Code
   │
   ├── supports → Agent
   │
   ├── supports → AgentSwarm
   │
   └── uses → K3

하지만 중요한 것은 관계 자체가 아니다.

각 Claim에 Source가 연결되어 있어야 한다.

Claim
   │
   └── source_id
          │
          ▼
       Source

예:

{
  "id": "claim:kimi-swarm",
  "kind": "claim",
  "label": "Kimi Code includes AgentSwarm",
  "source_ids": [
    "src:kimi-tools"
  ],
  "status": "verified",
  "rev": 1
}

11. Source Provenance

Source도 별도의 Entity로 관리한다.

{
  "id": "src:kimi-tools",
  "url": "...",
  "retrieved_at":
    "2026-08-26T00:00:00Z",
  "sha256": "<content-hash>"
}

이렇게 하면 단순히

"Agent가 그렇게 말했다"

가 아니라

Claim
 ↓
Source
 ↓
Source Hash

구조가 만들어진다.

12. Knowledge Graph 최소 Schema

실전에서는 다음 필드 정도면 충분하다.

id
kind
type
source_ids
status
rev
confidence
observed_at
valid_from
valid_to

status는 다음과 같이 운영할 수 있다.

proposed
verified
rejected
superseded

특히 LLM이 추론한 관계라면:

confidence

를 별도로 기록하는 것이 좋다.

13. 그래프는 처음부터 Neo4j일 필요가 없다

MVP에서는 오히려 JSONL이 편하다.

graphops/

├── kg/
│   ├── schema.json
│   ├── nodes.jsonl
│   ├── edges.jsonl
│   ├── sources.jsonl
│   ├── events.jsonl
│   ├── inbox/
│   └── snapshots/
│
├── dag/
│   └── pipeline.yaml
│
├── runs/
└── artifacts/

JSONL의 장점은 명확하다.

inspect
append
diff
hash
backup
Git

모두 쉽다.

14. Single Writer 원칙

여러 Agent가 동시에 Knowledge Graph를 수정하면 충돌하기 쉽다.

따라서 다음 구조가 좋다.

Research Agent ─┐
Analysis Agent ─┼─→ kg/inbox
Crawler Agent ──┘

                    ↓

            Knowledge Steward

                    ↓

             authoritative KG

Agent는 직접 Graph를 수정하지 않는다.

대신 Patch를 제출한다.

최종 반영은 Knowledge Steward 하나만 수행한다.

이것이 Single Writer Pattern이다.

15. Obsidian을 Human View로 사용할 수도 있다

JSONL을 Source of Truth로 유지하면서 사람이 보기 좋은 형태를 별도로 만들 수 있다.

예:

Knowledge Graph
      │
      ├─ nodes.jsonl
      ├─ edges.jsonl
      │
      └─ Markdown Generator
              ↓
          Obsidian Vault

한 Node를 하나의 Markdown 파일로 만든다.

---
id: product:kimi-code
kind: product
status: verified
---

# Kimi Code

## Relations

- [[Agent]]
- [[AgentSwarm]]
- [[K3]]

AI가 사용하는 데이터와 사람이 읽는 UI를 분리하는 것이다.

16. DAG는 Execution Graph다

Knowledge Graph와 DAG를 혼동하면 안 된다.

Knowledge Graph:

무엇을 알고 있는가?

DAG:

무엇을 먼저 실행해야 하는가?

예를 들어:

observe
   ↓
 plan
 ┌─┴─────┐
 ↓       ↓
research compare
 └───┬───┘
     ↓
   review
     ↓
    act

이를 YAML로 표현하면:

nodes:

  - id: observe
    needs: []

  - id: plan
    needs:
      - observe

  - id: research
    needs:
      - plan

  - id: compare
    needs:
      - plan

  - id: review
    needs:
      - research
      - compare

  - id: act
    needs:
      - review

17. Ready Frontier

DAG Scheduler는 현재 실행 가능한 Node를 계산한다.

예를 들어:

observe ✓
plan    ✓

research pending
compare  pending
review   pending

현재 Ready Frontier는:

research
compare

두 작업은 서로 의존하지 않으므로 동시에 실행할 수 있다.

       ┌→ Research Agent
Plan ──┤
       └→ Compare Agent

이럴 때 AgentSwarm을 활용한다.

18. AgentSwarm은 DAG 전체를 관리하면 안 된다

Swarm에게 다음과 같이 맡기면 위험하다.

"전체 프로젝트 알아서 끝내."

그 대신 Dispatcher가 Ready Node만 계산한다.

DAG Dispatcher
       ↓
Ready Frontier
       ↓
AgentSwarm

예:

ready_nodes = [
  research,
  compare,
  benchmark
]

각 Agent에게는 자신의 Node 정보만 전달한다.

19. Node State

각 실행 Node에는 상태가 필요하다.

pending
   ↓
running
   ↓
succeeded

실패하면:

running
   ↓
failed
   ↓
retry

부모 Node가 영구 실패하면 자식은:

blocked

가 된다.

예:

{
  "run_id": "2026-08-26-001",
  "nodes": {
    "research": {
      "status": "succeeded",
      "attempt": 1,
      "output_sha256": "..."
    },
    "review": {
      "status": "pending",
      "attempt": 0
    }
  }
}

20. Knowledge Graph + DAG 결합

둘을 합치면 다음 구조가 된다.

Knowledge Graph
      │
      ▼
Immutable Snapshot
      │
      ▼
     DAG
      │
      ▼
 Ready Frontier
      │
      ▼
Kimi Agents / Grok Bots
      │
      ▼
 Candidate Patch
      │
      ▼
 Knowledge Steward
      │
      ▼
Knowledge Graph

즉 Loop가 생긴다.

KNOW
 ↓
PLAN
 ↓
EXECUTE
 ↓
VERIFY
 ↓
LEARN
 ↓
KNOW

이것이 Graph + Loop Engineering이다.

21. Context Engineering

Agent가 실패하는 또 하나의 이유는 Context가 계속 커지는 것이다.

전체 대화 내역을 매번 전달하면 다음 문제가 발생한다.

Context 증가
 ↓
관련 없는 정보 증가
 ↓
Attention 분산
 ↓
Instruction 충돌
 ↓
Agent Drift

그래서 Context Pack을 따로 관리한다.

context/

├── mission.md
├── constraints.md
├── definitions.md
├── state.md
└── acceptance-tests.md

22. Context Pack의 역할

예를 들어:

mission.md

이 시스템이 해결하려는 문제

constraints.md

절대 하면 안 되는 작업

definitions.md

프로젝트 용어 정의

state.md

현재 상태

acceptance-tests.md

완료 판정 기준

Agent에게 과거 전체 대화를 주는 대신 필요한 Operational Context만 준다.

23. Handoff Envelope

Agent 사이의 작업도 자유로운 메시지보다는 Contract가 좋다.

예:

{
  "run_id": "run_01",

  "task": "...",

  "allowed_paths": [
    "/project/src"
  ],

  "allowed_tools": [
    "Read",
    "Grep"
  ],

  "prohibited_actions": [
    "delete",
    "publish"
  ],

  "acceptance_tests": [],

  "approval_boundary":
    "external_effect",

  "expected_artifact":
    "analysis.json",

  "next_owner":
    "verifier"
}

이것을 Handoff Envelope라고 생각하면 된다.

24. Harness Engineering

LLM은 Capability를 제공한다.

하지만 LLM 자체가 시스템의 통제 장치는 아니다.

예를 들어:

K3

는 Model이다.

Kimi Code

는 K3를 실행하는 Harness다.

그리고:

Grok Bot

은 또 다른 Runtime/Control Layer다.

따라서 다음처럼 이해하는 것이 좋다.

Model
   ↓
Inner Harness
   ↓
Outer Harness
   ↓
External Systems

25. Nested Harness

이번 구조에서는 다음과 같다.

Grok Bot
Outer Harness
      │
      ▼
Kimi Code
Inner Harness
      │
      ▼
K3

여기에는 중요한 문제가 있다.

Outer Harness가 Kimi Code 프로세스를 실행하도록 승인했다고 해서 그 안에서 발생하는 모든 Tool Call까지 승인한 것은 아니다.

이를 Nested Harness Gap이라고 볼 수 있다.

26. 이중 Policy Layer

따라서 권한 정책도 두 군데 필요하다.

Outer Policy
Grok Bot

+

Inner Policy
Kimi Code

Outer Policy:

Publish → approval
Delete → approval
Send → approval
Production change → approval
Purchase → approval

Inner Policy:

Read → allow
Grep → allow

Write → ask
Edit → ask
Bash → ask

rm -rf → deny
mail.send → deny

27. Least Privilege

Agent에게 필요한 권한만 주는 것이 중요하다.

예를 들어 Research Agent에게는:

Read
Search
Browser

정도만 준다.

다음 권한은 필요하지 않다.

Write
Delete
Send
Deploy
Payment

Worker Profile을 역할별로 나누는 이유다.

28. Read-only Agent부터 시작한다

처음 구축할 때는 다음 Agent 하나면 충분하다.

Read
Grep
Glob
Agent
AgentSwarm

제외:

Bash
Write
Edit
Write-capable MCP

이 Agent가 안정적으로 동작한 다음 하나씩 권한을 늘리는 것이 안전하다.

29. Append Log

Agent 시스템에서는 일반 Application Log보다 상태 전환 기록이 특히 중요하다.

예를 들어:

{
  "v": 1,
  "ts": "2026-08-26T12:00:00Z",
  "run_id": "run_01",
  "actor": "kimi",
  "event": "tool.request",
  "tool": "Bash",
  "decision": "ask",
  "status": "pending"
}

기록할 이벤트 예시는 다음과 같다.

handoff.created
tool.request
approval.result
tool.result
checkpoint
handoff.completed
recovery.started
recovery.completed

30. Hash Chain

Append Log를 조금 더 강하게 만들려면 이전 Record Hash를 포함할 수 있다.

Record 1
 hash=A

Record 2
 prev=A
 hash=B

Record 3
 prev=B
 hash=C

즉:

R1 → R2 → R3 → R4

중간 로그가 변경되면 이후 Hash Chain이 깨진다.

다만 이것만으로 동일한 OS 사용자가 로그를 수정하는 것을 완전히 막을 수 있는 것은 아니다.

중요한 시스템이라면 Chain Head를 외부 Immutable Storage에도 저장하는 구조를 고려할 수 있다.

31. 로그에 Secret을 넣으면 안 된다

다음 데이터는 Operational Log에서 제거한다.

API Token
Cookie
Password
OAuth Secret
Private Key
Raw credential

대신 필요한 경우 Hash를 기록한다.

{
  "args_sha256": "..."
}

32. 전체 시스템 구조

지금까지의 구조를 하나로 연결하면 다음과 같다.

                 ┌──────────────────┐
                 │     Human        │
                 │    Approval      │
                 └────────┬─────────┘
                          │
                 ┌────────▼─────────┐
                 │    Grok Bot      │
                 │ Outer Controller │
                 └────────┬─────────┘
                          │
        ┌─────────────────┼───────────────────┐
        │                 │                   │
        ▼                 ▼                   ▼
 Knowledge Graph      DAG Scheduler       Policy Gate
        │                 │
        │                 ▼
        │          Ready Frontier
        │                 │
        │                 ▼
        │           ┌───────────┐
        │           │ Kimi Code │
        │           └─────┬─────┘
        │                 │
        │                 ▼
        │                K3
        │          ┌──────┴──────┐
        │          │             │
        │        Agent        AgentSwarm
        │          │             │
        └──────────┴──────┬──────┘
                          │
                          ▼
                    Candidate Patch
                          │
                          ▼
                       Verify
                          │
                          ▼
                 Knowledge Steward
                          │
                          ▼
                  Knowledge Graph

33. 여기서 가장 중요한 것은 Swarm이 아니다

많은 Agent 프레임워크가 강조하는 것은 다음과 같다.

10 Agents
50 Agents
100 Agents
300 Agents

하지만 운영 시스템에서 더 중요한 것은 Agent 숫자가 아니다.

다음 구조다.

Task Contract
State
Verification
Return Path
Stop Condition
Approval Boundary
Evidence
Audit Log

Agent가 100개여도 이 구조가 없으면 시스템은 불안정해진다.

반대로 Agent가 세 개뿐이어도 이 구조가 있으면 상당히 강력한 자동화 시스템을 만들 수 있다.

34. 추천 구축 순서

처음부터 Knowledge Graph와 DAG와 Swarm을 모두 구축하는 것은 권장하지 않는다.

Stage 1 — Single Worker

Coordinator
 ↓
Worker
 ↓
Verifier

조건:

Read-only
3 Round Limit
Human Approval

Stage 2 — Output Contract

모든 Agent 결과를:

JSON Schema

로 만든다.

그리고:

validate
hash
persist

한다.

Stage 3 — Loop Controller

추가한다.

Retry
Stop Rule
Fingerprint
Idempotency

Stage 4 — DAG

독립적인 작업을 발견하면 DAG를 만든다.

research
compare
benchmark

같은 작업을 병렬 처리한다.

Stage 5 — AgentSwarm

Ready Frontier에 여러 Node가 있을 때만 Swarm을 사용한다.

Ready Frontier
     ↓
AgentSwarm

Swarm이 전체 시스템을 통제하게 하지 않는다.

Stage 6 — Knowledge Graph

다음 단계에서 장기 Memory를 추가한다.

조건은 하나다.

모든 Claim에는 Source가 있어야 한다.

Stage 7 — External Actions

마지막에 다음 기능을 추가한다.

Send
Publish
Deploy
Delete
Payment

그리고 반드시:

Human Approval
+
Idempotency
+
Live Verification

을 적용한다.

35. 실제 MVP 구조

처음 만든다면 이 정도면 충분하다.

agent-system/

├── AGENTS.md

├── context/
│   ├── mission.md
│   ├── constraints.md
│   ├── state.md
│   └── acceptance-tests.md

├── handoffs/
│   ├── inbox/
│   └── outbox/

├── runs/
│   └── <job_id>/
│       ├── task.json
│       ├── candidate.json
│       ├── verdict.json
│       └── events.jsonl

├── policy/
│   ├── tools.md
│   └── approvals.md

└── artifacts/

이 단계에서는 Knowledge Graph도 필요 없다.

DAG도 필요 없다.

Swarm도 필요 없다.

먼저 다음 Loop가 정확하게 동작하는지 확인한다.

Task
 ↓
Worker
 ↓
Candidate
 ↓
Verifier
 ↓
PASS / REVISE
 ↓
State

36. 다음 단계

이 구조가 안정되면:

Loop
 ↓
DAG
 ↓
Swarm
 ↓
Knowledge Graph

순으로 확장한다.

반대 방향으로 가면 시스템 복잡도가 빠르게 증가한다.

37. 핵심 원칙

이 전체 아키텍처를 다섯 문장으로 정리할 수 있다.

Models give capability.

모델은 시스템에게 능력을 준다.

Loops give persistence.

Loop는 작업이 실패해도 다시 진행할 수 있게 만든다.

Graphs give memory and order.

Knowledge Graph는 기억을, DAG는 실행 순서를 제공한다.

Context gives the correct frame.

Context Engineering은 Agent가 지금 필요한 정보만 보게 만든다.

Harnesses give control.

Harness는 Agent가 무엇을 할 수 있고 무엇을 해서는 안 되는지 통제한다.

결국 신뢰할 수 있는 AI Agent 시스템의 핵심은 더 강력한 모델이나 더 많은 Agent가 아니다.

Capability
     +
Loop
     +
Graph
     +
Context
     +
Harness
     +
Policy
     +
Evidence

이 구조가 갖춰졌을 때 비로소 AI Agent를 단순한 챗봇이 아니라 지속적으로 업무를 수행하는 운영 시스템으로 발전시킬 수 있다.

Flutter Signals 실전 가이드

행복한 수지아빠 — Wed, 26 Aug 2026 14:17:28 +0900

Riverpod과 무엇이 다르고, 언제 사용해야 하는가

기준일: 2026년 8월 26일

패키지확인된 최신 버전

signals / signals_flutter	7.1.0
riverpod / flutter_riverpod	3.4.2

Signals 7.1.0은 세밀한 반응성, 자동 의존성 추적, 지연 계산, 부분적인 위젯 재빌드를 중심으로 설계되어 있습니다. Riverpod 3.4.2는 반응형 캐시, 데이터 바인딩, 비동기 상태, 의존성 주입, 생명주기와 테스트 오버라이드를 함께 다루는 프레임워크에 가깝습니다. (Dart packages)

1. 먼저 결론부터

Signals와 Riverpod은 모두 Flutter 상태를 반응형으로 관리하지만, 추상화 수준이 다릅니다.

Signals
└─ 값을 반응형으로 만드는 핵심 프리미티브

Riverpod
├─ 상태 관리
├─ 의존성 주입
├─ 비동기 캐시
├─ 생명주기
├─ 스코프
├─ 오버라이드
└─ 테스트 컨테이너

Signals 공식 문서도 Signals를 완성형 애플리케이션 프레임워크가 아니라, 다른 DI 방식과 함께 사용할 수 있는 핵심 반응성 라이브러리로 설명합니다. Riverpod은 공식적으로 반응형 캐싱 및 데이터 바인딩 프레임워크를 표방합니다. (dartsignals.dev)

[Inference] 실무적인 선택을 요약하면 다음과 같습니다.

상황우선 검토

화면 내부의 간단한 상태	Signals
편집기, 게임 UI, 실시간 수치처럼 자주 바뀌는 상태	Signals
기존에 GetIt, Provider 등 DI가 구축된 프로젝트	Signals 추가 도입
API 요청, 캐시, 재시도, 무효화가 많은 앱	Riverpod
테스트에서 구현체를 자주 교체해야 하는 앱	Riverpod
기능과 팀 규모가 큰 애플리케이션	Riverpod 또는 혼합 구조
이미 Riverpod으로 안정적으로 운영 중인 프로젝트	Riverpod 유지
Riverpod의 인프라와 Signals의 세밀한 UI 반응성이 모두 필요	Riverpod + Signals

기존 Riverpod 프로젝트를 Signals로 전면 교체해야 할 일반적인 이유는 크지 않습니다. Signals가 필요한 화면이나 기능부터 제한적으로 넣는 편이 위험이 작습니다.

2. Signals란 무엇인가

Signals의 핵심은 값을 읽은 곳을 자동으로 기억한다는 것입니다.

Signal<T>
    │
    ├── Computed<R>
    │       │
    │       ├── UI
    │       └── 다른 Computed
    │
    └── Effect

예를 들어 count.value를 SignalBuilder 안에서 읽으면, Signals가 해당 SignalBuilder와 count 사이의 의존성을 자동으로 연결합니다.

이후 count.value가 변경되면 count를 읽었던 SignalBuilder만 다시 빌드됩니다. 의존성을 직접 등록하는 ref.watch, addListener, notifyListeners와 같은 코드가 필요하지 않습니다. Signals는 이러한 자동 의존성 추적과 부분 재빌드를 핵심 기능으로 제공합니다. (Dart packages)

3. 설치 방법

Flutter에서는 통합 패키지인 signals를 설치하는 방식이 권장됩니다.

flutter pub add signals

Flutter 코드에서는 다음 경로로 가져옵니다.

import 'package:signals/signals_flutter.dart';

signals 통합 패키지는 실행 환경에 따라 Dart용 또는 Flutter용 바인딩을 제공하며, Flutter 전용 패키지인 signals_flutter를 직접 설치하는 방법도 있습니다. 현재 Flutter용 최신 안정 버전은 7.1.0입니다. (dartsignals.dev)

4. Signals의 네 가지 핵심 요소

4.1 signal: 변경 가능한 상태

signal()은 값을 담는 반응형 컨테이너를 만듭니다.

final count = signal(0);

void increment() {
  count.value++;
}

void reset() {
  count.value = 0;
}

값 읽기와 쓰기 모두 .value를 사용합니다.

print(count.value);

count.value = 10;

다만 .value를 읽었다고 해서 항상 구독되는 것은 아닙니다. SignalBuilder, SignalWidget, computed, effect처럼 반응성 컨텍스트 내부에서 읽었을 때 의존성이 등록됩니다. (Dart packages)

4.2 computed: 파생 상태

기존 상태로부터 계산되는 값은 computed()로 만듭니다.

final count = signal(0);

final doubled = computed(() {
  return count.value * 2;
});

final isEven = computed(() {
  return count.value.isEven;
});

사용할 때는 일반 Signal과 마찬가지로 .value를 읽습니다.

print(doubled.value);
print(isEven.value);

computed에는 다음 특성이 있습니다.

읽힐 때 계산되는 지연 평가 방식입니다.
의존성이 변경되지 않았다면 이전 계산 결과를 재사용합니다.
콜백 내부에서 읽은 Signal을 자동으로 추적합니다.
조건문에 따라 실제로 읽는 Signal이 바뀌면 의존성도 동적으로 조정됩니다.
네트워크 요청이나 다른 Signal 변경 같은 부수 효과를 넣지 않는 것이 원칙입니다.

공식 문서도 computed 콜백을 순수 함수로 유지하고, 데이터베이스·네트워크 작업이나 다른 Signal 쓰기를 피하도록 설명합니다. (dartsignals.dev)

4.3 effect: 상태 변화에 따른 부수 효과

UI를 만드는 것이 아니라 로깅, 저장, 분석 이벤트 등의 작업을 실행해야 한다면 effect()를 사용합니다.

final count = signal(0);

final stopEffect = effect(() {
  debugPrint('현재 count: ${count.value}');
});

count.value++;
count.value++;

// 더 이상 effect가 필요하지 않을 때
stopEffect();

effect() 안에서 읽은 Signal이 변경되면 콜백이 다시 실행됩니다. effect()는 정리 함수도 반환하므로, 기능이나 위젯의 수명이 끝날 때 호출해야 합니다. (Dart packages)

잘못된 예: 순환 업데이트

final count = signal(0);

effect(() {
  count.value++;
});

이 코드는 count를 읽고 다시 변경하므로 effect가 자신을 계속 실행하는 순환 구조가 됩니다.

수정 방법

가능한 경우 상태 변경 로직을 effect 바깥의 명령 메서드로 옮기는 것이 좋습니다.

final count = signal(0);

void increment() {
  count.value++;
}

final stopEffect = effect(() {
  debugPrint('count changed: ${count.value}');
});

특수한 상황에서는 peek()이나 untracked()로 구독 없이 값을 읽을 수 있지만, 일반적인 상태 흐름에서는 .value가 우선입니다. (Dart packages)

4.4 batch: 여러 상태를 한 번에 변경

서로 관련된 Signal을 연속으로 변경할 때는 batch()를 사용할 수 있습니다.

final firstName = signal('Kim');
final lastName = signal('Minsoo');

final fullName = computed(
  () => '${firstName.value} ${lastName.value}',
);

void updateName() {
  batch(() {
    firstName.value = 'Park';
    lastName.value = 'Jisoo';
  });
}

batch() 안에서 여러 Signal을 변경하면 콜백이 끝나는 시점에 관련 구독자와 effect가 정리된 상태로 갱신됩니다. 중간 상태마다 effect가 반복 실행되는 상황을 줄일 수 있습니다. (Dart packages)

5. Flutter UI에서 Signals 사용하기

Signals 7에서는 다음 세 가지가 중심 API입니다.

API사용 시점

SignalBuilder	기존 위젯 안의 일부 영역만 반응형으로 만들 때
SignalWidget	StatelessWidget 전체가 Signal을 사용할 때
SignalStatefulWidget	StatefulWidget 생명주기와 Signal 반응성이 모두 필요할 때

예전 자료에서 자주 보이는 Watch 위젯과 SignalsMixin은 현재 deprecated 상태입니다. 신규 코드는 SignalBuilder, SignalWidget, SignalStatefulWidget을 기준으로 작성하는 것이 맞습니다. (dartsignals.dev)

5.1 SignalBuilder: 가장 명확한 부분 재빌드

import 'package:flutter/material.dart';
import 'package:signals/signals_flutter.dart';

final count = signal(0);
final doubled = computed(() => count.value * 2);

class CounterPage extends StatelessWidget {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Signals Counter'),
      ),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const Text('이 텍스트는 count를 구독하지 않습니다.'),

            SignalBuilder(
              builder: (context) {
                return Column(
                  children: [
                    Text('Count: ${count.value}'),
                    Text('Doubled: ${doubled.value}'),
                  ],
                );
              },
            ),

            const SizedBox(height: 16),

            ElevatedButton(
              onPressed: () => count.value++,
              child: const Text('증가'),
            ),
          ],
        ),
      ),
    );
  }
}

SignalBuilder는 builder 안에서 읽은 Signal을 동적으로 추적합니다. 값이 바뀌면 주변 CounterPage 전체가 아니라 해당 SignalBuilder가 반환하는 영역이 다시 빌드됩니다. 공식 문서도 가능한 한 작은 하위 영역에 배치하는 패턴을 권장합니다. (dartsignals.dev)

5.2 SignalWidget: 위젯 자체를 반응형으로 만들기

class CounterText extends SignalWidget {
  const CounterText({super.key});

  @override
  Widget build(BuildContext context) {
    return Text(
      '현재 값: ${count.value}',
      style: Theme.of(context).textTheme.headlineMedium,
    );
  }
}

SignalWidget의 build() 안에서 동기적으로 읽은 Signal은 자동 구독됩니다.

class CounterPanel extends SignalWidget {
  const CounterPanel({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: ${count.value}'),
        Text('Doubled: ${doubled.value}'),
        Text('Even: ${count.value.isEven}'),
      ],
    );
  }
}

count가 변경되면 CounterPanel 요소가 다시 빌드됩니다. 위젯 내부의 아주 작은 부분만 갱신해야 한다면 SignalWidget 전체 대신 SignalBuilder를 더 아래쪽에 배치하는 편이 적합합니다. (Dart packages)

5.3 SignalStatefulWidget: 로컬 상태와 생명주기

class SearchPage extends SignalStatefulWidget {
  const SearchPage({super.key});

  @override
  State<SearchPage> createState() => _SearchPageState();
}

class _SearchPageState extends State<SearchPage> {
  final query = signal('');
  late final void Function() stopLoggingEffect;

  @override
  void initState() {
    super.initState();

    stopLoggingEffect = effect(() {
      debugPrint('검색어 변경: ${query.value}');
    });
  }

  @override
  void dispose() {
    stopLoggingEffect();
    query.dispose();

    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            TextField(
              onChanged: (value) {
                query.value = value;
              },
            ),
            const SizedBox(height: 16),
            Text('현재 검색어: ${query.value}'),
          ],
        ),
      ),
    );
  }
}

SignalStatefulWidget는 State의 build()가 실행되는 동안 동기적으로 읽은 Signal을 추적합니다. 비동기 콜백, 이벤트 리스너 또는 지연 작업 안에서 나중에 읽은 값은 build() 의존성으로 등록되지 않습니다. (dartsignals.dev)

6. Controller 또는 Store 패턴으로 사용하기

전역 변수로 Signal을 바로 선언하면 예제는 간단하지만, 규모가 커지면 상태 변경 위치를 추적하기 어려워집니다.

실제 프로젝트에서는 다음과 같이 변경 가능한 Signal을 비공개로 두고, 외부에는 ReadonlySignal을 노출하는 구조가 적합합니다.

import 'package:signals/signals_flutter.dart';

class CounterController {
  final Signal<int> _count = signal(0);

  late final Computed<int> _doubled = computed(
    () => _count.value * 2,
  );

  ReadonlySignal<int> get count => _count;
  ReadonlySignal<int> get doubled => _doubled;

  void increment() {
    _count.value++;
  }

  void decrement() {
    _count.value--;
  }

  void reset() {
    _count.value = 0;
  }

  void dispose() {
    _doubled.dispose();
    _count.dispose();
  }
}

UI는 Signal 값을 직접 수정하지 않고 Controller 메서드를 호출합니다.

class CounterView extends SignalWidget {
  const CounterView({
    required this.controller,
    super.key,
  });

  final CounterController controller;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: ${controller.count.value}'),
        Text('Doubled: ${controller.doubled.value}'),
        ElevatedButton(
          onPressed: controller.increment,
          child: const Text('증가'),
        ),
        ElevatedButton(
          onPressed: controller.reset,
          child: const Text('초기화'),
        ),
      ],
    );
  }
}

ReadonlySignal은 외부 소비자가 .value를 직접 변경하지 못하게 하고, 상태 변경을 Controller 메서드로 모으는 데 사용됩니다. 공식 문서에서도 private Signal과 public ReadonlySignal을 결합하는 방식을 단방향 상태 흐름 패턴으로 소개합니다. (dartsignals.dev)

7. 비동기 API 호출

Signals는 futureSignal()을 통해 Future를 AsyncState 형태로 표현할 수 있습니다.

final userId = signal(1);

final user = futureSignal(() async {
  // await 이전에 동기적으로 읽었으므로 의존성으로 추적됩니다.
  final id = userId.value;

  return userRepository.fetchUser(id);
});

userId.value가 바뀌면 user FutureSignal이 무효화되고 새로운 요청을 실행합니다.

userId.value = 2;

UI에서는 AsyncState.map()으로 로딩, 성공, 오류를 분기할 수 있습니다.

class UserView extends SignalWidget {
  const UserView({super.key});

  @override
  Widget build(BuildContext context) {
    return user.value.map(
      loading: () {
        return const CircularProgressIndicator();
      },
      data: (value) {
        return Text(value.name);
      },
      error: (error, stackTrace) {
        return Text('사용자 조회 실패: $error');
      },
    );
  }
}

FutureSignal은 다음 작업도 제공합니다.

user.refresh(); // 기존 데이터를 유지하면서 다시 요청
user.reload();  // 기존 상태를 버리고 Loading부터 다시 시작
user.reset();   // 초기 상태로 되돌림

Future 콜백 안에서 Signal을 의존성으로 만들려면 기본적으로 await 이전에 동기적으로 읽어야 합니다. await 이후 읽은 Signal까지 추적해야 할 경우에는 AsyncSignalOptions의 명시적 dependencies 설정이 필요합니다. (dartsignals.dev)

8. Riverpod의 현재 권장 사용 방식

Riverpod 3에서 사용자 액션에 따라 변경되는 상태는 Notifier 또는 AsyncNotifier가 중심입니다. 예전 코드에서 많이 사용되던 StateNotifier보다 현재 공식 문서의 권장 방향에 가깝습니다. (riverpod.dev)

Riverpod 카운터 예제

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

final counterProvider =
    NotifierProvider<CounterNotifier, int>(
  CounterNotifier.new,
);

class CounterNotifier extends Notifier<int> {
  @override
  int build() {
    return 0;
  }

  void increment() {
    state++;
  }

  void reset() {
    state = 0;
  }
}

class CounterPage extends ConsumerWidget {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);

    return Scaffold(
      body: Center(
        child: Text('Count: $count'),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          ref
              .read(counterProvider.notifier)
              .increment();
        },
        child: const Icon(Icons.add),
      ),
    );
  }
}

Riverpod에서는 다음 역할이 명시적으로 구분됩니다.

// UI 또는 다른 Provider가 상태를 구독
final value = ref.watch(counterProvider);

// 상태 변경 객체를 한 번 읽음
final notifier = ref.read(counterProvider.notifier);

// 상태 변경에 따른 부수 효과
ref.listen(counterProvider, (previous, next) {
  debugPrint('$previous -> $next');
});

// 캐시를 버리고 다시 계산
ref.invalidate(counterProvider);

ref.watch는 선언적인 구독, ref.listen은 부수 효과, ref.read는 버튼 클릭과 같은 명령 실행에 사용됩니다. (riverpod.dev)

9. Signals와 Riverpod 상세 비교

비교 항목SignalsRiverpod

기본 성격	세밀한 반응성 프리미티브	반응형 캐싱 및 데이터 바인딩 프레임워크
상태 정의	signal(value)로 객체 생성	Provider, NotifierProvider 등 선언
상태 읽기	.value	ref.watch(provider)
상태 변경	.value =, Controller 메서드	Notifier 메서드와 state
의존성 추적	반응성 컨텍스트에서 읽은 Signal을 자동 추적	ref.watch로 의존성을 명시
파생 상태	computed()	Provider 안에서 다른 Provider를 ref.watch
부수 효과	effect(), SignalEffect	ref.listen()
UI 연결	SignalBuilder, SignalWidget	ConsumerWidget, Consumer
비동기 상태	FutureSignal, AsyncState	FutureProvider, AsyncNotifier, AsyncValue
캐시	반응성 값 자체의 계산 캐시 중심	Provider 결과 캐시가 핵심 개념
DI	별도 DI, 생성자 주입, SignalProvider 등 선택	Provider 그래프 자체가 DI 역할
스코프	직접 설계하거나 SignalProvider 활용	ProviderScope, ProviderContainer
구현 교체	생성자 주입 또는 사용 중인 DI에서 처리	Provider override가 내장됨
자동 정리	Signal 옵션, Provider 또는 명시적 dispose	autoDispose, ref.onDispose, keepAlive
파라미터 상태	직접 Factory 또는 Store 구조 설계	family 또는 codegen 파라미터
테스트	Controller를 일반 Dart 객체로 테스트 가능	ProviderContainer.test, override 제공
코드 생성	필수 아님	선택 사항
DevTools	초기 단계의 Signals DevTools 제공	전용 DevTools와 이전 상태 검사 제공

Signals의 의존성은 .value를 읽는 순간 자동으로 구성됩니다. Riverpod은 ref.watch를 통해 Provider 간 의존성을 코드에 명시하며, Provider의 반환값을 캐시합니다. (Dart packages)

Riverpod은 Provider별 자동 정리, ref.onDispose, keepAlive, 스코프별 override, 테스트 전용 ProviderContainer를 기본 설계에 포함합니다. Signals에서는 Signal 자체의 생명주기나 사용 중인 DI 컨테이너의 생명주기에 맞춰 관리해야 합니다. SignalProvider가 직접 생성한 Signal은 위젯 트리에서 제거될 때 dispose됩니다. (riverpod.dev)

10. 재빌드 방식 비교

Signals

SignalBuilder(
  builder: (context) {
    return Text('${count.value}');
  },
);

builder 안에서 실제로 읽은 Signal을 자동 추적합니다. count가 변경되면 해당 SignalBuilder만 다시 빌드됩니다.

Riverpod

class CountText extends ConsumerWidget {
  const CountText({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);

    return Text('$count');
  }
}

Riverpod은 counterProvider의 출력값이 변경되면 CountText를 다시 빌드합니다.

객체의 일부 속성만 구독하고 싶다면 select를 사용합니다.

final userName = ref.watch(
  userProvider.select((user) => user.name),
);

Riverpod 공식 문서는 select가 불필요한 재빌드를 줄일 수 있지만, 읽기 비용과 코드 복잡도가 조금 추가되므로 성능 측정 없이 일괄 적용하지 말라고 설명합니다. (riverpod.dev)

성능에 대한 정확한 해석

Signals는 반응성 단위를 잘게 나누기 쉽습니다. 그러나 이것만으로 모든 애플리케이션에서 Riverpod보다 빠르다고 결론내릴 수는 없습니다.

성능은 다음 요소의 영향을 함께 받습니다.

SignalBuilder 또는 Consumer의 배치 위치
상태 객체의 크기
변경 빈도
위젯 트리 깊이
리스트 및 이미지 렌더링 비용
API 호출 및 직렬화 비용
파생 상태 계산량
불변 객체 생성량

[Inference] 실무에서는 대표 화면을 대상으로 Flutter DevTools의 rebuild 통계와 프레임 시간을 측정한 후 판단하는 것이 적절합니다. Riverpod 공식 문서 역시 최적화 전에 벤치마크할 것을 권고합니다. (riverpod.dev)

11. 생명주기 비교

Signals

전역 Signal은 애플리케이션 종료까지 유지할 수 있지만, 기능 단위 상태라면 소유자가 명확해야 합니다.

class EditorStore {
  final title = signal('');
  final content = signal('');

  void dispose() {
    title.dispose();
    content.dispose();
  }
}

class EditorHostState extends State<EditorHost> {
  late final EditorStore store;

  @override
  void initState() {
    super.initState();
    store = EditorStore();
  }

  @override
  void dispose() {
    store.dispose();
    super.dispose();
  }
}

또는 SignalProvider가 Signal 생성과 정리를 담당하게 할 수 있습니다.

SignalProvider<MySignal>(
  create: () => MySignal(),
  child: const FeaturePage(),
);

외부에서 이미 만든 인스턴스를 제공하고 Provider가 dispose하지 않게 하려면 .value 생성자를 사용합니다.

SignalProvider<MySignal>.value(
  value: existingSignal,
  child: const FeaturePage(),
);

SignalProvider의 기본 생성자는 내부에서 생성한 Signal의 생명주기를 관리하고, .value 생성자는 외부 인스턴스의 생명주기에 관여하지 않습니다. (dartsignals.dev)

Riverpod

final searchProvider = Provider<SearchService>(
  isAutoDispose: true,
  (ref) {
    final service = SearchService();

    ref.onDispose(service.dispose);

    return service;
  },
);

Riverpod codegen을 사용하면 자동 정리가 기본값이며, codegen을 사용하지 않을 때는 isAutoDispose: true로 활성화할 수 있습니다. 마지막 리스너가 제거된 뒤 한 프레임 동안 다시 사용되지 않으면 Provider 상태가 제거되고 ref.onDispose가 호출됩니다. (riverpod.dev)

12. 테스트와 의존성 교체

Signals 테스트

Controller가 Flutter에 의존하지 않는다면 일반 Dart 단위 테스트로 검증할 수 있습니다.

void main() {
  test('increment increases count', () {
    final controller = CounterController();

    controller.increment();

    expect(controller.count.value, 1);

    controller.dispose();
  });
}

Repository를 생성자로 받도록 만들면 테스트 구현체를 직접 전달할 수 있습니다.

class LoginController {
  LoginController(this.repository);

  final AuthRepository repository;
  final loading = signal(false);

  Future<void> login() async {
    // ...
  }
}

final controller = LoginController(
  FakeAuthRepository(),
);

Riverpod 테스트

Riverpod은 Container와 Provider override가 정식 API로 포함되어 있습니다.

void main() {
  test('provider override example', () {
    final container = ProviderContainer.test(
      overrides: [
        authRepositoryProvider.overrideWithValue(
          FakeAuthRepository(),
        ),
      ],
    );

    final repository = container.read(
      authRepositoryProvider,
    );

    expect(repository, isA<FakeAuthRepository>());
  });
}

모든 Provider는 ProviderScope 또는 ProviderContainer에서 다른 값이나 구현으로 교체할 수 있습니다. 이 기능은 테스트뿐 아니라 개발·운영 환경별 구현 교체에도 활용됩니다. (riverpod.dev)

[Inference] 복잡한 의존성 그래프에서 테스트마다 Repository, API, 인증 상태를 교체해야 한다면 Riverpod의 override 체계가 더 구조적입니다. Signals는 일반 객체 테스트가 단순하지만, DI 및 스코프 체계는 프로젝트가 직접 선택해야 합니다.

13. Riverpod 코드를 Signals로 옮길 때의 대응 관계

RiverpodSignals에서의 유사 개념

NotifierProvider	Controller 또는 Store + private Signal
ref.watch(provider)	반응성 컨텍스트에서 signal.value 읽기
Provider 파생값	computed()
ref.listen()	effect()
ref.read(provider.notifier).method()	Controller 메서드 호출
FutureProvider	futureSignal()
AsyncValue<T>	AsyncState<T>
ref.invalidate()	FutureSignal의 reload, refresh, reset 또는 직접 상태 초기화
autoDispose	SignalProvider, 명시적 dispose, Signal 옵션
family	파라미터별 Controller Factory 또는 별도 DI 구조
Provider override	생성자 주입, DI override, SignalProvider.value
ProviderScope	별도 DI Scope 또는 SignalProvider 트리

중요한 점은 완전한 일대일 변환이 아니라는 것입니다.

예를 들어 Riverpod의 Provider는 단순 계산 함수만 의미하지 않습니다. ProviderContainer 내부의 캐시, 생명주기, 의존성 그래프와 함께 동작합니다. 따라서 Riverpod의 Provider를 무조건 computed()로 바꾸면 캐시 무효화와 스코프 의미가 달라질 수 있습니다. (riverpod.dev)

14. Riverpod과 Signals를 함께 사용하는 방법

Signals 공식 문서에는 Riverpod Provider가 Signal을 생성해 제공하는 예제가 포함되어 있습니다. 즉, 두 라이브러리는 기술적으로 배타적인 관계가 아닙니다. (dartsignals.dev)

[Inference] 실무에서는 다음과 같이 역할을 구분할 수 있습니다.

Riverpod
├─ API Client
├─ Repository
├─ 로그인 세션
├─ 앱 설정
├─ 원격 데이터 캐시
└─ 기능별 Store 생성 및 생명주기

Signals
├─ 화면 입력 상태
├─ 편집기 선택 상태
├─ 드래그 좌표
├─ 확대·축소 배율
├─ 재생 위치
└─ 자주 변경되는 파생 UI 값

혼합 예제

final editorRepositoryProvider =
    Provider<EditorRepository>((ref) {
  return EditorRepositoryImpl();
});

final editorStoreProvider = Provider<EditorStore>((ref) {
  final repository = ref.watch(
    editorRepositoryProvider,
  );

  final store = EditorStore(repository);

  ref.onDispose(store.dispose);

  return store;
});

Riverpod으로 Store 생성과 수명을 관리하고, Store 내부에서는 Signals를 사용합니다.

class EditorStore {
  EditorStore(this.repository);

  final EditorRepository repository;

  final zoom = signal(1.0);
  final selectedLayerId = signal<String?>(null);
  final isSaving = signal(false);

  late final canZoomIn = computed(
    () => zoom.value < 4.0,
  );

  void zoomIn() {
    if (!canZoomIn.value) {
      return;
    }

    zoom.value += 0.1;
  }

  void selectLayer(String id) {
    selectedLayerId.value = id;
  }

  void dispose() {
    canZoomIn.dispose();
    zoom.dispose();
    selectedLayerId.dispose();
    isSaving.dispose();
  }
}

UI에서는 Riverpod으로 Store 인스턴스를 받고, SignalBuilder로 필요한 영역만 구독합니다.

class EditorToolbar extends ConsumerWidget {
  const EditorToolbar({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final store = ref.watch(editorStoreProvider);

    return SignalBuilder(
      builder: (context) {
        return Row(
          children: [
            Text(
              '${(store.zoom.value * 100).round()}%',
            ),
            IconButton(
              onPressed: store.canZoomIn.value
                  ? store.zoomIn
                  : null,
              icon: const Icon(Icons.zoom_in),
            ),
          ],
        );
      },
    );
  }
}

[Inference] 이 구조에서는 Riverpod이 애플리케이션 수준의 의존성과 생명주기를 담당하고, Signals가 기능 내부의 세밀한 반응성을 담당합니다. 만화 편집기, 오디오 플레이어, 지도, 게임 UI처럼 빈번한 상태 변경이 있는 프로젝트에 적용하기 좋은 형태입니다.

15. Signals 사용 시 주의할 점

15.1 build() 안에서 Signal을 생성하지 않기

@override
Widget build(BuildContext context) {
  // 잘못된 위치
  final count = signal(0);

  return Text('${count.value}');
}

위젯이 다시 빌드될 때마다 새로운 Signal 인스턴스가 생성됩니다.

Signal은 다음 위치 중 하나에 두는 것이 적절합니다.

Controller 또는 Store 필드
State 객체의 필드
Provider 또는 DI Container
애플리케이션 수명과 동일한 제한적 전역 상태

Signals는 build() 안에서 Signal을 생성하는 패턴을 탐지하는 별도 lint 패키지도 제공합니다. (dartsignals.dev)

15.2 SignalWidget을 지나치게 크게 만들지 않기

class EntireHomePage extends SignalWidget {
  // 수많은 Signal을 읽는 매우 큰 위젯
}

이 위젯에서 여러 Signal을 읽으면 그중 하나만 바뀌어도 해당 위젯 요소가 다시 빌드됩니다.

변경 빈도가 다른 영역은 작은 위젯이나 SignalBuilder로 분리하는 편이 적절합니다.

Column(
  children: [
    const StaticHeader(),
    SignalBuilder(
      builder: (_) => CounterSection(),
    ),
    SignalBuilder(
      builder: (_) => ProgressSection(),
    ),
  ],
);

Signals 공식 문서도 부분 재빌드를 위해 SignalBuilder를 작은 하위 영역에 배치하는 패턴을 설명합니다. (dartsignals.dev)

15.3 effect에서 상태를 무분별하게 변경하지 않기

effect(() {
  total.value = price.value * quantity.value;
});

이 값이 파생 상태라면 effect보다 computed()가 적합합니다.

final total = computed(
  () => price.value * quantity.value,
);

effect는 로깅, 파일 저장, 분석 이벤트, 외부 시스템 호출처럼 반응형 그래프 밖으로 나가는 작업에 사용하는 편이 좋습니다. 파생 상태는 computed로 표현해야 지연 계산과 캐시 특성을 활용할 수 있습니다. (dartsignals.dev)

15.4 List를 제자리에서 수정할 때 주의하기

다음과 같이 기존 List 인스턴스를 제자리에서 수정하면 일반적인 값 비교만으로 변경이 감지되지 않을 수 있습니다.

final todos = signal<List<Todo>>([]);

todos.value.add(newTodo);

새 객체를 할당하는 방식이 명확합니다.

todos.value = [
  ...todos.value,
  newTodo,
];

또는 강제 갱신이 필요한 경우 다음 API를 사용할 수 있습니다.

todos.value.add(newTodo);
todos.set(todos.value, force: true);

Signals에는 ListSignal, MapSignal, SetSignal과 같은 반응형 컬렉션도 포함되어 있습니다. (dartsignals.dev)

15.5 오래된 Watch 예제를 그대로 사용하지 않기

과거 예제:

Watch(
  (context) => Text('$count'),
);

현재 방식:

SignalBuilder(
  builder: (context) {
    return Text('${count.value}');
  },
);

Signals 7 기준으로 Watch는 deprecated이며 SignalBuilder가 대체 API입니다. 또한 Signals 7의 SignalBuilder는 builder:라는 이름 있는 파라미터를 사용합니다. (dartsignals.dev)

16. 추천 프로젝트 구조

[Inference] Signals를 단순 전역 변수 모음으로 사용하기보다 기능별 Store 구조를 잡는 것이 유지보수에 유리합니다.

lib/
├─ core/
│  ├─ network/
│  ├─ storage/
│  └─ di/
│
├─ features/
│  └─ cart/
│     ├─ data/
│     │  ├─ cart_api.dart
│     │  └─ cart_repository_impl.dart
│     │
│     ├─ domain/
│     │  ├─ cart_item.dart
│     │  └─ cart_repository.dart
│     │
│     ├─ application/
│     │  └─ cart_store.dart
│     │
│     └─ presentation/
│        ├─ cart_page.dart
│        └─ cart_total_view.dart
│
└─ main.dart

cart_store.dart는 다음 원칙으로 구성할 수 있습니다.

class CartStore {
  CartStore(this.repository);

  final CartRepository repository;

  final Signal<List<CartItem>> _items = signal([]);

  final Signal<bool> _loading = signal(false);

  final Signal<Object?> _error = signal(null);

  ReadonlySignal<List<CartItem>> get items => _items;

  ReadonlySignal<bool> get loading => _loading;

  ReadonlySignal<Object?> get error => _error;

  late final Computed<int> itemCount = computed(
    () => _items.value.length,
  );

  late final Computed<int> totalPrice = computed(
    () => _items.value.fold(
      0,
      (sum, item) => sum + item.price * item.quantity,
    ),
  );

  Future<void> load() async {
    batch(() {
      _loading.value = true;
      _error.value = null;
    });

    try {
      _items.value = await repository.getItems();
    } catch (error) {
      _error.value = error;
    } finally {
      _loading.value = false;
    }
  }

  void remove(String itemId) {
    _items.value = _items.value
        .where((item) => item.id != itemId)
        .toList();
  }

  void dispose() {
    itemCount.dispose();
    totalPrice.dispose();
    _items.dispose();
    _loading.dispose();
    _error.dispose();
  }
}

핵심 규칙은 다음과 같습니다.

변경 가능한 Signal은 비공개로 둡니다.
외부에는 ReadonlySignal을 노출합니다.
UI는 Signal을 직접 수정하지 않고 Store 메서드를 호출합니다.
파생값은 computed로 표현합니다.
외부 부수 효과만 effect에 배치합니다.
Store를 생성한 계층이 Store의 정리도 담당합니다.

17. 최종 선택 기준

Signals가 잘 맞는 경우

[Inference]

상태 모델이 비교적 단순합니다.
코드 생성 없이 빠르게 개발하고 싶습니다.
화면의 일부 값이 자주 변경됩니다.
편집기, 플레이어, 게임, 지도처럼 세밀한 갱신이 중요합니다.
이미 GetIt, Provider 또는 자체 DI가 있습니다.
Controller를 일반 Dart 객체로 구성하고 싶습니다.
React, SolidJS, Preact 스타일의 반응성에 익숙합니다.

Riverpod이 잘 맞는 경우

[Inference]

Repository와 API 의존성이 많습니다.
비동기 상태와 캐시가 핵심입니다.
로그인 세션이나 앱 설정처럼 여러 화면이 공유하는 상태가 많습니다.
Provider 무효화와 자동 정리가 중요합니다.
테스트에서 의존성을 자주 교체합니다.
기능별 Scope가 필요합니다.
여러 개발자가 동일한 아키텍처 규칙을 따라야 합니다.
DevTools에서 전체 Provider 상태를 관찰하고 싶습니다.

Riverpod은 모든 Provider 상태를 확인하고 이전 상태를 살펴볼 수 있는 전용 Flutter DevTools 확장과 Riverpod 전용 lint/refactor 기능을 제공합니다. (riverpod.dev)

18. 종합 평가

[Inference] Signals는 Riverpod의 단순 대체재라기보다, Riverpod보다 낮은 수준에서 반응성을 제공하는 도구로 보는 것이 정확합니다.

Signals가 주로 답하는 질문
“이 값이 바뀌었을 때 필요한 UI만 어떻게 반응시킬 것인가?”

Riverpod이 주로 답하는 질문
“상태를 어디서 생성하고, 캐시하고, 공유하고,
언제 제거하며, 테스트에서 어떻게 교체할 것인가?”

따라서 기존 Riverpod 프로젝트에서는 다음 전략이 가장 현실적입니다.

1. 현재 Riverpod 구조는 유지
2. 빈번하게 갱신되는 복잡한 화면을 선별
3. 해당 기능 내부에만 Signals Store 도입
4. Riverpod이 Store 생성과 dispose 담당
5. 실제 rebuild 및 frame 성능 측정
6. 효과가 확인된 영역만 점진적으로 확대

앱 전체가 API 중심의 일반적인 업무 앱이라면 Riverpod만으로 충분한 경우가 많습니다. 반대로 만화 편집기, 실시간 자막, 오디오 재생 위치, 지도 이동, 드래그·리사이즈, 게임 HUD처럼 짧은 시간에 여러 값이 반복적으로 바뀌는 화면에서는 Signals 또는 Riverpod과 Signals의 혼합 구조를 검토할 가치가 있습니다.

Grok Bot으로 ‘문제 발견 → 검증 → 제품 출시 → 판매’ 자동화 시스템 구축하기

행복한 수지아빠 — Wed, 26 Aug 2026 09:34:35 +0900

단순히 AI에게 “돈 될 만한 사업 아이디어를 찾아줘”라고 요청하는 것과, 인터넷에서 실제 사업자의 문제를 지속적으로 수집하고 검증한 뒤 제품 출시까지 연결하는 시스템을 만드는 것은 완전히 다른 문제다.

Chris가 공개한 시스템의 핵심은 하나다.

아이디어를 생성하지 말고, 시장에서 반복해서 관찰되는 문제를 찾아라.

하나의 Reddit 글이나 한 사람의 불평만으로 제품을 만들지 않는다. 서로 독립된 여러 데이터 소스에서 동일한 문제가 발견되었을 때만 후보로 승격한다.

전체 구조는 다음과 같다.

인터넷 데이터 수집
       ↓
문제 추출
       ↓
Embedding / Clustering
       ↓
복수 Source Confirmation
       ↓
Scoring
       ↓
사람의 승인
       ↓
사업 전용 Agent 생성
       ↓
Landing Page + Checkout
       ↓
시장 검증
       ↓
제품 구축
       ↓
Outreach / 판매
       ↓
매출·비용 측정
       ↓
Kill / Scale
       ↓
결과를 다시 Scoring에 반영

즉, AI 사업 아이디어 생성기가 아니라 AI 기반 Revenue Discovery Engine에 가깝다.

1. 가장 중요한 설계 원칙: Single Source를 믿지 않는다

이 시스템에서 가장 중요한 것은 LLM 자체가 아니다.

Cross-source confirmation, 즉 서로 다른 종류의 데이터가 동일한 문제를 가리키는지를 확인하는 것이다.

예를 들어 Reddit에서 다음 이야기가 나왔다고 하자.

HVAC 업체가 갑자기 결원이 생겼을 때 면허가 있는 대체 기술자를 구하기 어렵다.

이것 하나만으로는 사업 아이디어가 아니다.

하지만 동시에 다음 데이터가 발견된다면 이야기가 달라진다.

Reddit
↓
HVAC 업체 사장이 긴급 대체 인력을 찾기 어렵다고 말함

Indeed
↓
비슷한 업무를 담당할 Dispatcher / Technician 채용 다수

Upwork
↓
긴급 dispatch 관련 반복 업무 의뢰

Podcast
↓
HVAC 운영자가 같은 문제 언급

Google News
↓
폭염으로 HVAC 수요 급증

이 경우 하나의 문제가 여러 시스템에서 독립적으로 검증된다.

Chris의 시스템은 이를 Convergence라고 본다.

2. 왜 데이터 수집 시스템을 5개로 나누는가

하나의 Scraper가 인터넷을 뒤지는 구조가 아니다.

각 시스템마다 다른 종류의 증거를 담당한다.

System 1 — 사람들이 이미 돈을 쓰는 문제

가장 가치 있는 신호다.

수집 대상 예:

Upwork
Fiverr
Indeed
App Store 리뷰
SaaS 1~3점 리뷰
Flippa
Acquire

여기서 찾는 것은 단순한 불만이 아니다.

"이 문제를 해결하기 위해 이미 돈이 나가고 있는가?"

예를 들어 회사가 특정 반복 업무를 처리하기 위해 연봉 $45,000 직원을 고용하고 있다면 그 업무에는 이미 시장 가격이 존재한다.

또 SaaS 리뷰에 다음과 같은 내용이 있다면 강한 신호다.

매월 $130를 내고 있는데
내가 필요한 것은 기능 하나뿐이다.

이 경우 새로운 SaaS 전체를 만드는 것이 아니라 그 사람이 사용하는 핵심 기능 하나만 떼어낸 Micro SaaS가 기회가 될 수 있다.

3. System 2 — 전문가와 운영자들이 이야기하는 방향

두 번째 데이터는 Podcast와 YouTube다.

원문에서는 다음 프로그램을 예로 들었다.

My First Million
This Week in Startups
Lenny's Podcast
AI Daily Brief
Greg Isenberg 관련 콘텐츠

그러나 중요한 것은 프로그램 이름이 아니다.

자신이 공략하려는 Vertical에 맞춰 채널을 선택해야 한다.

예를 들어 건설업을 대상으로 한다면

SaaS Podcast

보다

Contractor Podcast
HVAC Podcast
Construction Business Podcast
Roofing Operator Channel

같은 데이터가 훨씬 가치 있다.

구조는 단순하다.

YouTube RSS
     ↓
새 Video 감지
     ↓
Transcript 수집
     ↓
LLM Extraction
     ↓
Problem / Tool / Idea 추출
     ↓
기존 Cluster와 비교

Podcast에서 발견된 아이디어는 독립적으로 Candidate가 되지 않는다.

이 시스템에서는 Confirmation Source 역할을 한다.

즉,

Podcast에서만 언급
→ Watching

Reddit 문제 + Podcast 언급
→ Score 상승

Job Posting + Review + Podcast
→ Candidate 가능

이런 구조다.

4. System 3 — Timing Catalyst 탐지

사업에서는 문제 자체만큼 중요한 것이 타이밍이다.

예를 들어 다음과 같은 이벤트가 발생할 수 있다.

새로운 규제
보험 정책 변경
폭풍
폭염
가뭄
Permit 정책 변경
보조금 정책
License 규정

이것들이 기존 문제와 결합하면 갑자기 구매 의사가 커진다.

그래서 System 3는 다른 시스템보다 자주 실행한다.

원문의 예시는 2시간 간격이다.

수집 후보:

Google News RSS
County Permit Portal
Business Registration
Contractor License Board
NOAA Weather
Regulation Update

여기서 중요한 데이터는 다음 네 가지다.

Who
어떤 사업자가 영향을 받는가?

Where
어느 지역인가?

Urgency
얼마나 급한가?

Window
기회가 얼마 동안 지속되는가?

예를 들어:

강력한 우박 예보
       ↓
Roofing Contractor
       ↓
향후 2~4주 수요 증가
       ↓
Lead / Scheduling / Financing 문제 증가

기존 Cluster와 Catalyst가 연결되면 즉시 Alert를 발생시킨다.

5. System 4 — 사업자의 실제 불만

Reddit과 전문 Forum을 읽는다.

하지만 여기에는 강력한 필터가 필요하다.

수집하지 않는 데이터:

직원 불평
일반 소비자 불만
정치
동기부여 글
성공담
잡담

찾는 것은 Owner 또는 Operator가 말하는 문제다.

특히 다음 문장이 강한 Signal이 된다.

"I wish there was..."

"Is there a tool that..."

"We currently pay..."

"I spend hours every week..."

"Alternative to..."

"Why is there no..."

추출 결과는 최대한 단순하게 만든다.

who: HVAC owner
problem: last-minute licensed technician replacement
vertical: HVAC
severity: 5
quote: "..."
source: URL

전문 산업 Forum은 Reddit보다 더 높은 Signal을 가질 수 있다.

예를 들어 Plumbing Forum에 글을 쓰는 사람은 실제 Plumbing Business 운영자일 가능성이 일반 Reddit보다 높기 때문이다.

6. System 5 — 무엇이 빠르게 성장하는가

마지막은 Launch / Trend 감지다.

예:

Product Hunt Top 20
GitHub Trending
Show HN
Ask HN

여기서는 단순히 숫자를 저장하지 않는다.

1,000 stars

보다

출시 48시간
1,000 stars

가 훨씬 의미 있기 때문이다.

따라서 반드시:

traction
+
age

를 함께 저장한다.

7. 수집 데이터와 사람이 보는 데이터를 분리한다

원문의 좋은 설계 중 하나가 이 부분이다.

Machine Layer와 Human Layer를 분리한다.

Machine Layer

SQLite 또는 Supabase.

예:

raw_items
problems
problem_embeddings
clusters
cluster_sources
enrichments
verdicts
outcomes
run_logs

예시 스키마:

raw_items
 ├ id
 ├ source_type
 ├ source_url
 ├ raw_text
 ├ author
 └ collected_at

problems
 ├ id
 ├ raw_item_id
 ├ problem
 ├ vertical
 ├ severity
 ├ dollar_amount
 └ embedding

clusters
 ├ id
 ├ canonical_problem
 ├ vertical
 ├ score
 ├ status
 └ updated_at

Vector Search를 사용해 새로운 Problem이 기존 Cluster와 유사한지 판단한다.

8. Human Layer는 Obsidian

Chris는 사람이 보는 인터페이스로 Obsidian을 사용한다.

예:

00-Inbox
01-Daily
02-Candidates
03-Watching
04-Proposals
05-Active
06-Outcomes
07-Dossiers
08-Killed

Cluster 하나가 Markdown 파일 하나가 된다.

예:

---
cluster_id: hvac-0021
score: 84.9
systems:
  - jobs
  - forum
vertical: hvac
status: candidate
verdict:
---

본문:

# Problem

HVAC 업체가 긴급 Call-out 상황에서
면허가 있는 대체 기술자를 찾기 어렵다.

## Evidence

Source A
Quote
URL

Source B
Quote
URL

## Diagnostic

...

## Enrichment

...

여기에서 매우 중요한 규칙이 있다.

사람이 변경한 Frontmatter가 항상 우선한다.

Agent가 Obsidian을 업데이트하기 전에 반드시 기존 Frontmatter를 다시 읽는다.

그래야 사람이

status: killed

로 변경한 아이디어를 AI가 다시 Candidate로 되돌려 놓는 문제를 방지할 수 있다.

9. 핵심은 Clustering

수백 개 글을 그대로 사람이 읽는 것은 자동화가 아니다.

예를 들어:

576 Raw Items
↓
72 Problems
↓
57 Clusters
↓
1 Candidate

처럼 압축해야 한다.

새로운 Problem이 들어오면:

Problem
   ↓
Embedding
   ↓
Vector Search
   ↓
Existing Cluster?
   ├ YES → attach
   └ NO  → new cluster

여기에 추가로 LLM 판단을 넣을 수 있다.

Semantic Similarity
+
LLM Classification

두 단계를 같이 쓰는 것이 안정적이다.

10. Scoring Engine

원문의 가장 중요한 아이디어 중 하나다.

Score는 단순한 LLM 느낌이 아니다.

가장 높은 Weight는

Distinct Systems Confirming

이다.

예를 들면 다음처럼 설계할 수 있다.

Score =

35% Source Diversity
20% Existing Spend Evidence
15% Severity
10% Recurrence
10% Growth Velocity
5% Timing Catalyst
5% Founder Preference

예:

Reddit 30개
Podcast 0
Jobs 0
Reviews 0

→ Source Diversity = 낮음

반대로:

Reddit 2
Indeed 4
Upwork 3
App Review 5

→ Source Diversity = 높음

후자가 훨씬 높은 점수를 받는다.

11. 인간 피드백까지 Scoring에 넣는다

사람이 Candidate를 판단할 때 세 가지 Verdict를 내린다.

Pursue
Watch
Kill

그리고 반드시 이유를 입력한다.

예:

Kill

Reason:
시장 규모는 충분하지만
고객 확보 비용이 너무 높을 가능성이 큼.

이 데이터가 쌓이면 다음 후보 평가에도 사용한다.

최근 30개 Verdict
↓
선호 Pattern
↓
Scoring Adjustment

즉 시스템이 시간이 지날수록

"시장에 뭐가 필요한가?"

뿐 아니라

"내가 어떤 사업을 실제로 하는가?"

까지 학습한다.

12. Candidate 기준

원문의 예시는 매우 보수적이다.

Score ≥ 70
+
2 Systems

→ Candidate

그리고

Score ≥ 85
+
3 Systems
+
Verified Numbers

→ Build Proposal

즉 50개 문제 중 1~2개만 올라오게 만드는 것이 목적이다.

아이디어가 많이 나오는 것은 좋은 시스템이 아니다.

버릴 것을 많이 버리는 시스템이 좋은 시스템이다.

13. Dashboard

사람이 판단하는 화면은 복잡할 필요가 없다.

홈 화면:

Problem                           Vertical   Score  Sources
──────────────────────────────────────────────────────────
Licensed technician shortage     HVAC        84.9     3
Insurance claim rework           Dental      81.2     2
Marketplace payout fee           SaaS        73.7     1

클릭하면:

Problem

Why this matters

Evidence
 ├ Quote
 ├ Source
 └ URL

Enrichment

Score Breakdown

[Pursue]
[Watch]
[Kill]

Reason: __________

여기서 중요한 것은 데이터 시각화보다 Decision Interface라는 점이다.

14. Pursue를 누르면 새로운 Agent를 만든다

Candidate Agent와 Business Agent를 분리한다.

Discovery Agent
       ↓
Human Pursue
       ↓
Business Agent 생성

Business Agent가 받는 Context:

Problem
Evidence
Quotes
Source URLs
Vertical
Competitors
Pricing Evidence
Customer List
Catalysts

그리고 각각 독립적으로 관리한다.

Business A
 ├ Revenue
 ├ Cost
 └ Customers

Business B
 ├ Revenue
 ├ Cost
 └ Customers

사업별 P&L을 섞지 않는 것이 중요하다.

15. 제품부터 만들지 않는다

가장 중요한 부분이다.

Pursue한 뒤 바로 제품 개발을 시작하지 않는다.

먼저 Test를 만든다.

Evidence
↓
Landing Page
↓
Price
↓
Checkout
↓
Traffic
↓
Payment Intent

Landing Page에는 실제 Evidence에서 나온 표현을 사용한다.

예를 들어 사업자가

"I spend three hours every morning rescheduling technicians."

라고 반복해서 말한다면,

마케팅 문구를 새로 만들어내기보다 문제 표현 자체를 활용한다.

다만 실제 외부 공개 시에는 저작권·개인정보·플랫폼 약관을 별도로 검토해야 한다.

16. Waitlist보다 Checkout

원문에서 상당히 강조하는 부분이다.

Waitlist
=
관심

Checkout
=
구매 의도

따라서 Landing Page 단계부터 가격을 제시한다.

예:

Emergency HVAC Dispatch Assistant

$299 / month

그리고 결제 단계까지 이동하는지를 측정한다.

여기서 실제 제품이 완성되지 않았다면 결제 처리 방식과 소비자 보호, 환불, 표시·광고 관련 법적 의무를 반드시 검토해야 한다.

17. 제품은 네 가지 형태 중 하나로 분류한다

문제가 검증되었다고 무조건 SaaS를 만들 필요는 없다.

원문에서는 네 가지 Shape로 분류한다.

① Tool

현재 쓰는 Software에 대한 불만이 반복될 때.

기존 제품 전체를 복제
X

불만이 집중된 기능 하나
O

Micro SaaS 형태다.

② Service

Job Posting 또는 Freelance Brief가 반복될 때.

기업이 이미 사람에게 맡기고 있는 Outcome을 자동화한다.

예:

Permit Runner

↓

AI + Workflow Automation

↓

Permit Processing Service

③ Physical Product

문제가 Screen 밖에서 발생한다면 물리 상품도 가능하다.

예:

작업 현장
매장
창고
차량

④ Information Product

반복적으로 동일한 질문이 등장하고 해결책이 지식이라면 정보 상품이다.

Guide
Template
Checklist
Database
Course
Report

18. 첫 번째 고객은 이미 데이터베이스에 있다

이 구조에서 상당히 흥미로운 점이다.

Problem Discovery 과정에서 이미 다음 사람들을 찾았다.

문제를 말한 사람
Job Posting을 올린 회사
Freelance Job을 발주한 사람
부정적 SaaS Review 작성자

즉 고객 Discovery와 Problem Discovery가 동시에 일어난다.

따라서 첫 Outreach 대상은:

Cluster Evidence
        ↓
Prospect List

에서 생성한다.

19. 그러나 Outreach는 자동 실행하지 않는다

원문에서도 사람에게 연락하거나 돈을 쓰는 행동에는 별도 승인을 둔다.

좋은 Permission Model이다.

Agent 자동 허용

Research
Problem extraction
Clustering
Landing page 작성
Prospect list 작성
Draft 작성
Dashboard 업데이트

Human Approval 필요

Email 전송
DM 전송
광고 집행
우편 발송
결제
가격 변경
환불
송금
외부 게시

즉:

AI can prepare.
Human authorizes irreversible actions.

라는 구조다.

20. 모든 사업에는 Kill Metric이 있어야 한다

사업을 시작한 뒤 AI가 계속 낙관적으로 해석하는 것을 막기 위한 장치다.

예:

14일

300명 Landing Page 방문

Checkout Click < 3

Payment = 0

→ Kill

또는

Outreach 100
Reply < 5
Qualified Lead < 2

→ Kill

제품을 만들기 전에 Kill Metric을 정의한다.

이렇게 해야 결과를 사후적으로 합리화하지 않는다.

21. Outcome이 다시 Discovery Engine으로 돌아간다

전체 시스템에서 가장 중요한 Feedback Loop다.

Idea
↓
Build
↓
Sell
↓
Outcome
↓
Scoring Engine

예를 들어

Roofing Lead Tool
Score 88
↓
Launch
↓
0 Sales
↓
Killed

결과를 저장한다.

다음에 유사한 Candidate가 나타나면:

Previous failure pattern

으로 반영한다.

반대로:

HVAC Dispatch
Score 86
↓
5 Customers
↓
MRR 발생

한다면 비슷한 특성을 가진 문제의 Score를 높일 수 있다.

이렇게 시스템이 점점 자신의 경험 데이터를 갖게 된다.

22. 전체 Cron 구조

예를 들면 다음과 같다.

07:00
System 1
Jobs / Reviews / Freelance

08:00
System 4
Forums / Reddit

08:30
System 5
Product Hunt / GitHub / HN

Every 2 Hours
System 3
News / Regulation / Weather / Permit

Event Driven
System 2
YouTube / Podcast RSS

23:00
Embedding
Clustering
Scoring
Verdict Learning

23:30
Obsidian Update
Dashboard Update

07:30
Morning Brief

23. Morning Brief

사람에게는 Raw Data를 전달하지 않는다.

예:

Morning Brief — 2026-08-26

NEW CANDIDATE

HVAC Emergency Technician Marketplace

Score: 86
Systems: 3

Evidence
- Job postings
- HVAC forum
- Upwork

Why now
Heat wave increased emergency callouts.

Expected customer
10~50 technician HVAC shop.

NEXT ACTION

Review proposal.

아무것도 변하지 않았다면:

No meaningful changes today.

한 줄로 끝낸다.

24. 구현한다면 Grok에 종속시킬 필요는 없다

이 글에서는 Grok Bot을 중심으로 설명하지만 구조 자체는 특정 LLM과 독립적이다.

예를 들어 다음 구조로 만들 수 있다.

                    ┌───────────────┐
                    │ Data Sources  │
                    └───────┬───────┘
                            ↓
                 ┌───────────────────┐
                 │ Collector Workers │
                 └─────────┬─────────┘
                           ↓
                     PostgreSQL
                           +
                     pgvector
                           ↓
                 Problem Extractor
                           ↓
                     Cluster Engine
                           ↓
                    Scoring Engine
                           ↓
               ┌────────────────────┐
               │ Decision Dashboard │
               └─────────┬──────────┘
                         ↓
                      Pursue
                         ↓
                 Business Agent
                         ↓
             Landing / Checkout Test
                         ↓
                   Sales Outcome
                         ↓
                 Feedback Engine

LLM은 다음 중 무엇이든 사용할 수 있다.

GPT
Claude
Gemini
Grok
Local LLM

핵심 자산은 모델이 아니라:

데이터
+
Cluster history
+
Verdicts
+
Outcomes

이다.

25. 현실적으로 가장 먼저 만들어야 할 MVP

처음부터 글의 모든 기능을 구현하는 것은 과도하다.

MVP라면 다음 6개만 있으면 된다.

1단계

Reddit / Forum
Jobs
App Reviews

3개 Source만 수집한다.

2단계

LLM으로 Problem extraction.

3단계

pgvector로 Clustering.

4단계

다음 세 요소만 Scoring.

Source diversity
Dollar evidence
Severity

5단계

Decision Dashboard.

Pursue
Watch
Kill

6단계

Pursue하면 자동으로:

Landing Page Draft
Pricing Proposal
Customer List
Validation Plan

까지만 생성한다.

실제 결제·연락·광고는 사람이 승인한다.

이 정도만 만들어도 원문 시스템의 핵심 가설을 검증할 수 있다.

결론

이 글에서 가장 중요한 것은 “Grok으로 사업을 자동으로 여러 개 돌릴 수 있다”는 화려한 문장이 아니다.

더 중요한 부분은 그 앞단의 구조다.

Search
↓
Evidence
↓
Convergence
↓
Filter
↓
Human Decision
↓
Experiment
↓
Revenue
↓
Outcome
↓
Learning

보통 AI 사업 아이디어 시스템은:

AI
↓
아이디어 100개

에서 끝난다.

이 시스템은 반대로:

인터넷 수백 개 Signal
↓
실제 문제 수십 개
↓
Cluster 수십 개
↓
검증된 Candidate 1~2개
↓
시장 테스트

를 목표로 한다.

그래서 이것을 단순한 AI 사업 자동화 Bot이라고 보는 것보다,

Continuous Problem Discovery + Evidence-based Venture Factory

또는

AI Revenue Discovery Engine

이라고 보는 것이 기술적으로 훨씬 정확하다.

그리고 이 구조에서 장기적으로 가장 가치 있는 것은 Agent도 Dashboard도 아니다.

결국 축적되는 핵심 자산은 다음 네 가지다.

1. 어떤 문제가 반복해서 발생했는가
2. 어떤 증거가 실제 매출로 이어졌는가
3. 어떤 아이디어를 왜 죽였는가
4. 어떤 유형의 사업이 실제로 돈을 벌었는가

이 데이터가 계속 축적되면 단순한 인터넷 모니터링 시스템이 아니라 자신의 사업 경험을 학습하는 개인용 Venture Intelligence System으로 발전할 수 있다.

출처 :

X에서 Chris(@everestchris6) 님

how to build revenue systems with grok bot (FULL GUIDE)

x.com

Growth Lab 분석: Coding Agent를 ‘성장팀’으로 바꾸는 파일 기반 Growth OS

행복한 수지아빠 — Tue, 25 Aug 2026 12:34:36 +0900

GitHub - tsingyuai/growth-lab: An end-to-end growth tool that understands the product, fetch the data it needs, researches the m

An end-to-end growth tool that understands the product, fetch the data it needs, researches the market, executes campaigns, and reviews results to improve the next round of growth. 从代码到市场的开源端到端增长工具...

github.com

AI를 이용한 마케팅 도구는 이미 많다.

블로그 글을 작성하는 AI도 있고, 경쟁사를 조사하는 AI도 있으며, SNS 콘텐츠를 생성하거나 SEO 키워드를 분석해 주는 서비스도 있다.

하지만 대부분은 하나의 작업만 처리한다.

문제는 실제 Growth 업무가 하나의 작업으로 끝나지 않는다는 것이다.

제품 이해
→ 사용자와 시장 조사
→ 성장 기회 발견
→ 실행
→ 결과 측정
→ 분석
→ 다음 실험

이 사이클을 계속 반복해야 한다.

오픈소스 프로젝트 Growth Lab은 바로 이 문제를 Coding Agent를 이용해 해결하려는 프로젝트다.

Growth Lab은 자신을 자연어로 제품 운영과 사용자 성장 루프를 실행하는 도구로 설명한다. 현재 Codex와 Claude Code를 Runtime으로 사용하고, 제품 분석부터 시장 조사, 콘텐츠·SEO 실행, 결과 회고까지 하나의 지속적인 루프로 연결한다.

GitHub: tsingyuai/growth-lab

핵심 아이디어는 의외로 단순하다

Growth Lab의 구조를 한 줄로 정리하면 다음과 같다.

대화 = Control Plane
Codex / Claude Code = Runtime
Model = 성장 루프
Collector = 데이터 수집
Executor = 실행
Memory = 실행 기록
SOUL.md = 제품에 대한 장기 이해

일반적인 SaaS 방식과 상당히 다르다.

별도의 복잡한 Workflow Engine을 구축하는 대신 Coding Agent가 이미 가지고 있는 파일 읽기, 코드 수정, 웹 검색, 브라우저 조작, 명령 실행 능력을 그대로 Runtime으로 사용한다.

즉 Growth Lab 자체가 거대한 애플리케이션이라기보다는,

Coding Agent가 Growth Engineer처럼 행동하도록 만들어 놓은 방법론 + 도구 + Memory 묶음

에 더 가깝다.

1. 가장 중요한 구조: Model → Collector → Executor → Memory

Growth Lab을 이해하려면 이 네 가지 개념을 먼저 봐야 한다.

                  ┌──────────────┐
                  │    Model     │
                  │ 성장 전략/루프 │
                  └──────┬───────┘
                         │
                Observe / Decide
                         │
            ┌────────────▼────────────┐
            │        Collector        │
            │ 시장·검색·콘텐츠 데이터 수집 │
            └────────────┬────────────┘
                         │
                       Evidence
                         │
                  ┌──────▼───────┐
                  │    Model     │
                  │    Decide    │
                  └──────┬───────┘
                         │
                       Action
                         │
            ┌────────────▼────────────┐
            │        Executor         │
            │ 페이지·콘텐츠·이미지·배포 │
            └────────────┬────────────┘
                         │
                       Result
                         │
                  ┌──────▼───────┐
                  │    Memory    │
                  │ 데이터·결과·다음 행동 │
                  └──────────────┘

Model은 개별 도구가 아니라 하나의 완전한 성장 사이클이다.

프로젝트 문서에서도 Model을 Observation → Action → Review 루프로 정의하고 있으며, 각 Model은 자신의 전용 Memory namespace를 갖는다.

현재 공개된 주요 Model은 다음과 같다.

models/
├── onboard-growth-lab
├── run-seo-page-loop
└── xhs-replicate

여기서 중요한 것은 단순히 Skill을 여러 개 만들어놓은 것이 아니라는 점이다.

예를 들어 SEO Model은

키워드 찾아줘

로 끝나는 게 아니다.

실제 정의는 다음 사이클을 갖는다.

Read Memory
→ Observe
→ Decide
→ Act
→ Review
→ Write Memory
→ Next Observation

즉 이전 실험 결과를 읽고, 현재 검색 시장을 다시 조사하고, 하나의 행동을 선택한 다음, 실제 페이지를 만들고 배포한 후 결과까지 다시 Memory에 기록한다.

이 구조가 Growth Lab의 핵심이다.

2. SOUL.md: AI가 제품 자체를 기억한다

Growth Lab에는 특이한 파일이 하나 있다.

SOUL.md

처음에는 대략 다음과 같은 빈 템플릿이다.

Product
- Name
- One-line description
- Product form
- Stage

Users and situations
- Current users
- Candidate users
- Situations of need
- Core job to be done

Value
- Problem solved
- Core value proposition
- Differentiation

Product reality
- Available capabilities
- Website and channels
- Analytics and data

Evidence and hypotheses
- Verified facts
- Active hypotheses
- Open questions

여기서 중요한 설계 원칙이 있다.

AI가 처음 제품을 보고 모든 것을 상상해서 채워 넣지 않는다.

제품 코드를 읽고 확인할 수 있는 사실, 사용자가 직접 알려준 사실, 아직 검증되지 않은 가설을 구분한다. 프로젝트의 Runtime 지침 역시 증거가 없는 내용을 사실로 쓰지 말라고 명시한다.

따라서 시간이 지나면서 다음처럼 제품 이해가 쌓인다.

1차 실행
제품 코드 분석
↓
제품이 무엇을 하는지 확인

2차 실행
시장 조사
↓
가능성이 높은 사용자 발견

3차 실행
SEO 실험
↓
어떤 검색 의도가 실제 트래픽을 만드는지 발견

4차 실행
콘텐츠 실험
↓
어떤 가치 제안에 반응하는지 발견

그리고 이 중 장기적으로 유효한 제품 지식은 다시 SOUL.md에 들어간다.

[Inference] 이 방식은 일반적인 LLM의 대화 Memory라기보다 제품에 대한 Agent-managed knowledge state에 가깝다.

3. Memory는 채팅 기록이 아니라 Growth 실험 로그다

각 Model은 별도의 Memory를 가진다.

예를 들어 SEO라면

memory/
└── run-seo-page-loop/

샤오홍슈 성장 루프라면

memory/
└── xhs-replicate/

형태다.

여기에는 단순한 대화 요약이 아니라 다음 내용이 기록된다.

관찰 데이터
시장 조사 결과
선택한 전략
실행한 작업
게시 URL
실행 시점
Baseline
성과 데이터
분석
다음 행동

따라서 Growth Agent는 다음 실행에서 과거 실험을 다시 읽을 수 있다.

지난번에 무엇을 했지?
        ↓
어떤 결과가 나왔지?
        ↓
그때 세운 다음 가설은 무엇이었지?
        ↓
이번에는 무엇을 시험해야 하지?

이것이 단발성 Prompt 사용과 가장 큰 차이다.

4. Collector는 Agent의 ‘눈’ 역할을 한다

현재 저장소의 collectors/에는 다음과 같은 수집 기능이 존재한다.

bing-webmaster
media-crawler
media-crawler-bilibili
media-crawler-douyin
media-crawler-kuaishou
media-crawler-tieba
media-crawler-weibo
media-crawler-zhihu
research-product
research-seo-demand
xiaohongshu-mcp

Collector의 역할은 명확하다.

Agent가 의사결정을 내리는 데 필요한 Evidence를 가져오는 것이다.

예를 들어 SEO라면

검색 수요
검색 결과
경쟁 페이지
SERP 구조
현재 Ranking

같은 데이터를 수집할 수 있다.

콘텐츠 Growth에서는

경쟁 콘텐츠
고성과 콘텐츠
트렌드
콘텐츠 구조
사용자 반응

등을 조사한다.

그리고 Agent가 직접 검색이나 브라우저를 사용할 수 있다면 굳이 별도의 Client를 만들지 않는다.

Growth Lab은 Runtime이 이미 가진 검색·브라우저·파일·코드 기능을 우선 활용하도록 설계되어 있다.

5. Executor는 실제 행동을 담당한다

Collector가 조사 담당이라면 Executor는 실행 담당이다.

현재 공개된 Executor에는 다음과 같은 것들이 있다.

create-seo-page
generate-image
indexnow
review-seo-page
review-seo-performance
screenshot-assets
xhs-render-cards

역할이 상당히 구체적이다.

예를 들어 SEO 루프에서는 다음 흐름이 만들어진다.

research-seo-demand
        ↓
create-seo-page
        ↓
generate-image
        ↓
review-seo-page
        ↓
제품 테스트
        ↓
Deploy
        ↓
IndexNow
        ↓
review-seo-performance

실제 SEO Model의 Skill에도 이 실행 순서가 정의되어 있다.

여기서 특히 흥미로운 부분은 review-seo-page다.

AI에게 단순히

이 글 괜찮아?

라고 묻는 구조가 아니다.

경쟁 페이지와 검색 의도, 정보 밀도, 사용자 가치, 증거, 차별화 등을 기준으로 페이지를 다시 검토하도록 구성한다.

SEO 페이지를 만들기 전에 후보 Query마다 상위 3~5개 주요 페이지를 분석하도록 요구하며, 검색량이나 검색 결과 제목만 보고 바로 콘텐츠를 생성하는 것을 금지하고 있다.

6. SEO 자동화가 아니라 ‘SEO 학습 루프’

일반적인 SEO AI 도구의 구조는 흔히 이렇다.

Keyword
↓
AI Article
↓
Publish

Growth Lab은 훨씬 길다.

기존 Memory 확인
↓
실제 검색 수요 조사
↓
SERP 분석
↓
경쟁 페이지 구조 분석
↓
Information Gap 발견
↓
하나의 Action 결정
↓
페이지 구현
↓
페이지 검수
↓
배포
↓
IndexNow
↓
성과 측정
↓
Memory 저장
↓
다음 Action

중요한 차이는 마지막 부분이다.

Publish가 종료 지점이 아니다.

성과를 다시 읽는다.

예를 들면 다음을 본다.

Discovery
Ranking
CTR
Search Intent Fit
Content usefulness
Conversion
AI visibility

그리고 결과를 기반으로

페이지 개선
Snippet 변경
Evidence 추가
Conversion 수정
새 Supporting Page 생성
관찰 기간 연장

중 하나를 다음 행동으로 결정한다.

이것이 Growth Loop다.

7. SNS 콘텐츠도 같은 구조로 처리한다

현재 구현된 또 다른 대표 Model은 중국 SNS 플랫폼 샤오홍슈(Xiaohongshu)용 xhs-replicate다.

전체 과정은 5단계다.

① Idea 탐색
↓
② 참고 콘텐츠 선택 + 구조 분석
↓
③ 실제 제품 내용 적용
↓
④ 이미지 생성 + 자동 검사
↓
⑤ 게시 결과 회수 + 회고

여기에는 의외로 세밀한 규칙들이 들어 있다.

예를 들어 인기 게시물을 참고한다고 해서 그대로 복제하지 않는다.

Skill에서는 다음과 같은 요소만 이전하도록 제한한다.

정보 계층
Proof 영역 비율
읽기 리듬
정보 밀도
Hook 구조

반면 다음 요소는 복제하지 않는다.

브랜드
원문 Copy
제품 UI
고유 Screenshot
고유 장식
정확한 Composition
전체 카드 순서

실제 제품 기능이 없는 내용 역시 만들어내지 않도록 제한한다.

예를 들어 참고 콘텐츠가 7장짜리 카드라고 해도 실제 제품 정보가 6장밖에 없다면 6장만 만든다.

또 콘텐츠 게시 전에 자동 검사도 수행한다.

check-compliance.py
check-banned-phrases.py

전자는 과장 표현, 외부 유도, 허위 보장 등의 표현을 검사하고, 후자는 반복적인 AI 문체를 줄이기 위한 검사다.

8. 사람이 완전히 빠지는 시스템은 아니다

Growth Lab이 흥미로운 또 다른 이유가 있다.

모든 것을 자동화하려 하지 않는다.

예를 들어 계정에 민감한 게시 작업에서는 Human-assisted publishing 방식을 사용한다.

Agent가

최종 콘텐츠
이미지
채널
게시 시점
설정
링크
게시 방법

을 포함하는 Publication Package를 만들고 사람이 실제 플랫폼 UI에서 게시한다.

그 뒤 게시 URL이나 Screenshot을 다시 Agent에게 전달해 후속 분석을 진행한다.

샤오홍슈 Model 역시 자동 게시를 하지 않고 실제 게시 결과를 24시간, 48시간, 7일 시점에 Memory에 저장하도록 구성되어 있다.

즉 목표는

Human 제거

가 아니라

Human 판단이 필요한 곳만 남기기

에 가깝다.

9. 또 하나의 중요한 결정: 데이터베이스가 없다

SEO Model에는 꽤 과감한 설계 원칙이 명시돼 있다.

Create no fixed schema,
database,
dashboard,
workflow state,
or task queue.

즉 별도의

PostgreSQL
Workflow DB
Queue
Dashboard
State Machine

을 기본 구조로 만들지 않는다.

대신 파일 시스템이 상태를 담당한다.

SOUL.md
SKILL.md
references/
memory/
outputs/

[Inference] 이는 Coding Agent가 이미 파일 시스템을 자유롭게 탐색하고 수정할 수 있다는 전제에서는 상당히 합리적인 선택이다.

전통적인 서비스라면 상태를 다음처럼 구현해야 한다.

Application
↓
API
↓
Database
↓
Workflow Engine
↓
Queue
↓
Worker

Growth Lab은 많은 부분을 다음으로 압축한다.

Coding Agent
↓
Files

덕분에 구조가 극도로 단순해진다.

10. 그래서 실제 사용법도 단순하다

설치는 저장소를 Clone하는 것으로 시작한다.

git clone https://github.com/tsingyuai/growth-lab.git
cd growth-lab

그다음 Codex 또는 Claude Code에서 해당 디렉터리를 연다.

그리고 자연어로 이야기한다.

이 제품을 분석해줘.

또는

이 제품의 첫 번째 성장 루프를 실행해줘.

또는

검색 수요를 조사해서
가장 가능성 높은 SEO 페이지 하나를 만들어줘.

혹은

최근 Growth 결과를 분석하고
다음 실험을 실행해줘.

Agent는 필요한 Model을 찾아 해당 SKILL.md를 읽고, 필요한 Collector와 Executor를 선택해 실행하도록 설계되어 있다.

11. API Key 관리도 Agent 방식이다

인증 정보는 repository 내부에 저장하지 않는다.

.env.local

또는 Process Environment Variable을 사용한다.

.env와 .env.local은 Git에서 제외하도록 구성되어 있으며, 필요한 기능에 대한 Credential만 선택적으로 설정한다.

예를 들어 샤오홍슈 수집은 API Key 방식이 아니라 Local MCP 서비스와 QR 로그인을 사용하고, 로그인 상태 역시 저장소 밖에 저장하도록 설계돼 있다.

이 역시 Git repository 자체를 Growth Workspace로 사용하기 위한 설계다.

12. 이 프로젝트에서 가장 주목할 부분

[Inference] Growth Lab에서 가장 흥미로운 부분은 SEO나 SNS 기능 자체보다 Agent Application Architecture다.

최근 Agent 시스템을 만들 때 흔히 다음부터 구현한다.

Workflow Builder
Agent DB
Vector DB
Task Queue
Scheduler
Admin Dashboard
Tool Router
Memory Server

Growth Lab은 반대로 접근한다.

이미 Coding Agent가 가지고 있는 능력을 최대한 활용한다.

Reasoning      → Codex / Claude Code
Tool Calling   → Coding Agent
Browser        → Runtime
Code Editing   → Runtime
Execution      → Runtime
Memory         → Files
Knowledge      → Markdown
Methodology    → Skill
Integration    → Collector / Executor

결과적으로 시스템에서 정말 필요한 부분만 남는다.

무엇을 관찰해야 하는가
무엇을 판단해야 하는가
어떤 행동을 해야 하는가
결과를 어떻게 측정해야 하는가
무엇을 다음 실행에 기억해야 하는가

즉 Agent 인프라보다 업무 방법론을 코드화하는 것에 집중한다.

13. 내가 이 프로젝트를 다시 정의한다면

[Inference] Growth Lab을 단순히

AI Growth Tool

이라고 부르는 것보다 다음 표현이 더 정확하다.

Coding Agent 위에서 실행되는 파일 기반 Growth Operating System

그리고 그 구조는 다음 공식으로 설명할 수 있다.

Agent Runtime
+
Domain Skills
+
Tools
+
Persistent Memory
+
Real-world Feedback
=
Learning Growth Agent

특히 중요한 것은 마지막의 Real-world Feedback이다.

LLM에게 계속 콘텐츠를 생성시킨다고 시스템이 발전하는 것은 아니다.

Growth Lab은 다음 사이클을 만들려고 한다.

AI가 가설 생성
↓
실제 행동
↓
실제 사용자 반응
↓
데이터 수집
↓
Memory
↓
다음 판단

이 구조가 반복되면 단순한 콘텐츠 생성기가 아니라 제품별 Growth history를 가진 Agent가 만들어진다.

결론

Growth Lab의 핵심은 AI에게 마케팅 글을 잘 쓰게 하는 것이 아니다.

Coding Agent가 제품을 이해하고 → 시장을 관찰하고 → 행동하고 → 실제 결과를 학습하도록 만드는 것이다.

이를 위해 복잡한 Agent 플랫폼 대신 상당히 단순한 구조를 선택했다.

SOUL
    제품에 대한 장기 이해

Model
    Observe → Act → Review 방법론

Collector
    세상을 관찰하는 도구

Executor
    실제 행동을 수행하는 도구

Memory
    실제 실험과 결과의 기록

Codex / Claude Code
    전체를 실행하는 Runtime

현재 공개 구현은 SEO 페이지 성장과 샤오홍슈 콘텐츠 성장에 집중되어 있다. README 역시 현재 SEO 페이지 루프와 샤오홍슈 수집·제작·회고 워크플로우를 주요 구현 기능으로 설명하고 있다.

[Inference] 그러나 구조 자체는 훨씬 범용적이다.

예를 들어 같은 패턴으로

YouTube Growth Model
App Store ASO Model
Instagram Growth Model
Product Hunt Launch Model
Email Marketing Model
Affiliate Growth Model
Community Growth Model
Paid Ads Model
Retention Model

같은 Model을 추가할 수 있다.

결국 Growth Lab이 보여주는 아이디어는 하나다.

AI Agent 시대에는 애플리케이션을 전부 새로 만들 필요가 없을 수도 있다.

Coding Agent 자체를 Runtime으로 사용하고, 우리가 정말 잘 만들어야 할 것은 그 위에서 실행되는 업무 방법론, 도구, 그리고 실제 결과를 기억하는 Feedback Loop일 수 있다.

Kiro cli 기본 사용방법 정리

행복한 수지아빠 — Tue, 25 Aug 2026 12:21:04 +0900

1. 설치 → 로그인 → 프로젝트에서 실행

macOS/Linux에서는 공식 설치 명령이 다음과 같습니다.

curl -fsSL https://cli.kiro.dev/install | bash

로그인:

kiro-cli login

로그인 상태 확인:

kiro-cli whoami

프로젝트로 이동해서:

cd ~/projects/my-project

kiro-cli

이렇게 하면 현재 디렉터리를 workspace로 삼아 Kiro가 실행됩니다. 일반적인 대화형 사용은 브라우저 로그인을 쓰며, API Key는 주로 CI/CD와 headless 모드용입니다. (Kiro)

2. 가장 기본적인 사용법은 그냥 자연어

실행 후에는 별도의 명령 문법을 배울 필요 없이 요청하면 됩니다.

> 이 프로젝트 구조를 분석해줘.

> 현재 인증 시스템이 어떻게 동작하는지 설명해줘.

> 로그인 API에서 발생할 수 있는 보안 문제를 찾아줘.

> 이 기능을 구현해줘.

> 테스트까지 작성하고 실행해줘.

Kiro는 필요에 따라 파일을 읽고, 코드를 수정하고, shell 명령을 실행합니다. 위험하거나 권한이 필요한 작업에는 승인 절차가 들어갑니다. (Kiro)

3. @파일은 반드시 알아두기

특정 파일을 정확하게 대상으로 지정할 때는 @를 사용합니다.

> @src/api/routes.ts 코드를 리뷰해줘.

> @package.json 을 보고 현재 기술 스택을 설명해줘.

> @src/auth/login.ts 에서 발생할 수 있는 버그를 찾아줘.

Tab 자동완성도 지원합니다.

이 기능은 꽤 중요합니다. 에이전트가 알아서 프로젝트 전체를 뒤지게 하는 것보다 내가 원하는 파일을 명시적으로 context로 주는 것이 빠르고 명확한 경우가 많습니다. (Kiro)

4. Shift + Tab — Plan Mode

큰 작업에서는 바로 코딩을 시키기보다 이것을 많이 쓰는 것이 좋습니다.

Shift + Tab

그러면 Plan mode가 됩니다.

예:

[plan] > 기존 JWT 인증 시스템을 OAuth + JWT 구조로 변경해줘.

바로 코드를 바꾸는 대신 먼저 구현 계획을 작성합니다.

1. 현재 인증 구조 분석
2. OAuth provider abstraction 설계
3. DB schema 변경
4. API route 수정
5. refresh token 처리
6. migration
7. 테스트

계획을 확인한 다음 실행 단계로 넘어갈 수 있습니다. 공식 문서에서도 복잡한 변경 전에 Plan mode를 사용하는 흐름을 안내합니다. (Kiro)

작은 수정

버튼 색깔 바꿔줘

→ 일반 모드

큰 수정

인증 구조 전체 리팩터링
결제 시스템 추가
DB schema 변경

→ Shift+Tab 권장

5. /spec — Kiro를 쓰는 중요한 이유 중 하나

상당히 큰 기능이라면 Plan보다 한 단계 더 체계적인 Spec workflow를 사용할 수 있습니다.

/spec new auth-system

그리고:

JWT 인증 + Role 기반 권한 시스템을 구현하고 싶어.

Kiro는 다음 구조를 만듭니다.

.kiro/specs/auth-system/

├── requirements.md
├── design.md
└── tasks.md

흐름은:

요구사항
   ↓
설계
   ↓
Task 분해
   ↓
구현
   ↓
검증

입니다. (Kiro)

기존 Spec 보기:

/spec

기존 Spec 계속하기:

/spec auth-system

Task 전체 실행:

/spec run auth-system

Kiro의 Spec은 CLI와 IDE가 같은 .kiro/specs/를 사용하므로 CLI에서 만들고 IDE에서 이어서 작업할 수도 있습니다. (Kiro)

제가 구분한다면:

작업사용

작은 수정	일반 Prompt
약간 복잡	Shift+Tab Plan
큰 Feature	/spec
반복하면서 완료까지 밀어붙이기	/goal

6. /goal — "될 때까지 반복해"

Kiro CLI에서 특히 알아둘 만한 기능입니다.

/goal 로그인 API를 리팩터링하고 모든 테스트가 통과하도록 해줘

Kiro가 한 번 작업하고 끝나는 것이 아니라:

구현
 ↓
테스트
 ↓
실패
 ↓
수정
 ↓
다시 테스트
 ↓
완료

식으로 반복합니다.

기본 최대 iteration은 5회입니다.

/goal --max 10 Jest 테스트를 전부 Vitest로 마이그레이션하고 모든 테스트가 통과하도록 해줘

중단:

/goal clear

중요한 점은 완료 조건을 구체적으로 써주는 것입니다.

좋지 않은 예:

/goal 코드를 개선해줘

좋은 예:

/goal auth 모듈을 리팩터링하고
npm test가 모두 통과하며
TypeScript error가 0개가 되도록 해줘

공식 문서도 /goal에서는 “all tests pass”, “no TypeScript errors” 같은 명확한 acceptance criteria를 주는 것을 권장합니다. (Kiro)

7. !명령어 — AI를 거치지 않고 바로 Shell 실행

CLI 안에서:

!npm run build

!npm test

!git status

라고 하면 Kiro에게 “이 명령을 실행해줘”라고 요청하는 것이 아니라 직접 Shell 명령을 실행합니다.

예를 들어:

> 로그인 기능 수정해줘.

Kiro 작업 완료

> !npm test

처럼 쓰면 편합니다. (Kiro)

8. /context — AI가 무엇을 보고 있는지 확인

코딩 에이전트에서 아주 중요한 명령입니다.

/context show

현재 context에 어떤 파일이 들어가 있고 얼마나 token을 사용하는지 볼 수 있습니다.

직접 추가:

/context add src/app.js

Glob도 됩니다.

/context add "src/**/*.ts"

제거:

/context remove src/app.js

전체 제거:

/context clear

(Kiro)

예를 들어 프로젝트가 커지면:

/context add "src/auth/**/*.ts"
/context add "src/db/**/*.ts"

처럼 현재 작업에 필요한 영역만 넣는 방식이 유용합니다.

9. .kiro/steering/ — 프로젝트 규칙을 Kiro에게 기억시키기

매번 다음처럼 말하고 싶지 않을 수 있습니다.

TypeScript 사용해
pnpm 사용해
Vitest 사용해
Server Component 우선해
any 사용하지 마

이런 프로젝트 규칙을 Steering에 넣습니다.

.kiro/
└── steering/
    └── project.md

예:

# Project Rules

- Next.js 15 + TypeScript
- Package manager: pnpm
- Database: PostgreSQL
- ORM: Drizzle
- Testing: Vitest
- Avoid `any`
- Prefer server components
- API responses follow REST conventions

Kiro는 workspace의 .kiro/steering/ 내용을 프로젝트 컨텍스트로 사용할 수 있습니다. 전역 규칙은:

~/.kiro/steering/

에 둘 수 있고, workspace 규칙이 global 규칙보다 우선합니다. (Kiro)

AGENTS.md도 지원합니다.

project/
├── AGENTS.md
├── src/
└── .kiro/

Kiro는 프로젝트 루트의 AGENTS.md도 자동으로 인식합니다. (Kiro)

10. /model — 모델 변경

현재 모델 선택:

/model

특정 모델 지정:

/model claude-opus-4.6

현재 모델을 기본값으로:

/model set-current-as-default

공식 CLI에서는 Tab completion도 지원합니다. (Kiro)

11. /agent — 작업별 전문 Agent 만들기

예를 들어 항상 같은 방식으로 코드 리뷰를 한다면:

/agent create code-reviewer

설명을 지정할 수도 있습니다.

/agent create code-reviewer -D "Security and code quality reviewer"

Agent 목록:

/agent list

전환:

/agent swap code-reviewer

편집:

/agent edit code-reviewer

기본 Agent 지정:

/agent set-default code-reviewer

(Kiro)

프로젝트 전용 Agent:

.kiro/agents/

전역 Agent:

~/.kiro/agents/

에 저장됩니다. 현재 공식 문서는 JSON과 Markdown 형식을 모두 지원한다고 설명합니다. (Kiro)

주의할 점

Custom Agent에서는 Steering이 자동으로 포함되지 않습니다.

필요하다면 Agent configuration에:

{
  "resources": [
    "file://.kiro/steering/**/*.md"
  ]
}

처럼 넣어야 합니다. 이 부분은 놓치기 쉽습니다. (Kiro)

12. Skills — 반복 작업을 /명령으로 만들기

Kiro도 Agent Skills를 지원합니다.

프로젝트용:

.kiro/skills/

전역:

~/.kiro/skills/

예:

.kiro/skills/pr-review/
└── SKILL.md

그러면 CLI에서:

/pr-review

처럼 사용할 수 있습니다.

Kiro는 Skill description과 요청이 맞으면 자동으로 활성화할 수도 있습니다. (Kiro)

즉,

Steering
= 프로젝트 규칙

Agent
= 역할

Skill
= 작업 절차

라고 이해하면 편합니다.

예를 들어:

.kiro/

steering/
  coding-rules.md

agents/
  backend.md
  reviewer.md

skills/
  pr-review/
  deploy/
  db-migration/

같은 구조가 가능합니다.

13. /tools — 권한 관리

Kiro가 계속:

Allow?
[y/n]

을 물어보면 도구를 신뢰하도록 만들 수 있습니다.

현재 Tool 확인:

/tools

특정 Tool trust:

/tools trust write

다시 승인 필요:

/tools untrust write

모두 trust:

/tools trust-all

초기화:

/tools reset

(Kiro)

다만 trust-all보다는 필요한 권한만 주는 방식이 안전합니다.

14. /chat, /rewind, /compact

이 세 개도 실제 사용 빈도가 높습니다.

새 대화:

/chat new

예전 작업 계속:

/chat resume

CLI 시작할 때 바로 resume:

kiro-cli chat --resume

특정 session:

kiro-cli chat --resume-id SESSION_ID

(Kiro)

대화가 엉뚱한 방향으로 갔다면:

/rewind

특정 시점:

/rewind 4

원래 대화를 파괴하는 것이 아니라 그 지점에서 새로운 conversation branch를 만듭니다. (Kiro)

Context가 너무 길어졌다면:

/compact

대화 핵심을 요약하고 context 공간을 확보합니다. (Kiro)

15. /guide — 명령어를 외울 필요가 없게 해주는 기능

이건 처음 Kiro CLI를 사용할 때 상당히 유용합니다.

/guide

그리고:

How do I configure MCP?

이 프로젝트에 적합한 steering을 만들어줘.

code review agent를 만들어줘.

처럼 물을 수 있습니다.

Guide Agent는 현재 설치된 Kiro CLI에 맞는 문서를 바탕으로 설명하고 .kiro/ 설정 파일까지 만들어줄 수 있습니다. 원래 Agent로 돌아갈 때는 Shift+Tab 또는 /agent swap을 사용할 수 있습니다. (Kiro)

16. MCP

GitHub, DB, API, 각종 외부 도구를 붙일 때 사용합니다.

현재 상태:

/mcp

인증 문제:

/mcp auth my-server

로그아웃:

/mcp logout my-server

Kiro의 MCP는 외부 데이터나 도구를 Agent에게 연결하는 역할입니다. (Kiro)

17. Headless — CI/CD 자동화

Kiro CLI는 터미널 대화 없이 한 번 실행하는 것도 가능합니다.

kiro-cli chat --no-interactive \
  "이 프로젝트의 보안 문제를 찾아줘"

Read/grep만 허용:

kiro-cli chat \
  --no-interactive \
  --trust-tools=read,grep \
  "src의 TODO를 전부 찾아줘"

모든 Tool 허용:

kiro-cli chat \
  --no-interactive \
  --trust-all-tools \
  "테스트를 만들고 실행해줘"

(Kiro)

CI에서는:

export KIRO_API_KEY=ksk_xxxxx

를 사용합니다.

예를 들어:

git diff | kiro-cli chat \
  --no-interactive \
  --trust-tools=read,grep \
  "이 변경사항을 코드 리뷰해줘"

같은 PR Review 자동화도 가능합니다. 공식 문서 역시 CI에서는 API Key를 secret으로 저장하고 --trust-all-tools보다 필요한 tool만 지정하는 것을 권장합니다. (Kiro)

18. 알아두면 좋은 단축키

키기능

Shift+Tab	Plan mode
Shift+Enter	여러 줄 Prompt
Ctrl+J	여러 줄 입력, 대부분 Terminal 지원
Ctrl+G	Subagent monitor
Ctrl+O	긴 Shell output 펼치기
Ctrl+S	명령/context 검색 및 queue steering
Esc	Agent 작업 취소
Tab	autocomplete / 승인 세부 옵션
Ctrl+D	CLI 종료

(Kiro)

제가 생각하는 Kiro CLI의 핵심 사용 흐름

처음 프로젝트를 열었으면 다음 순서가 가장 이해하기 쉽습니다.

cd project
     ↓
kiro-cli
     ↓
/guide
     ↓
프로젝트 분석
     ↓
.kiro/steering 작성
     ↓
@파일 + 일반 Prompt
     ↓
복잡하면 Shift+Tab
     ↓
큰 Feature면 /spec
     ↓
반복 실행이 필요하면 /goal
     ↓
테스트
     ↓
/rewind 또는 수정

특히 Steering + Plan + Spec + Goal + Skills 이 다섯 개를 이해하면 Kiro CLI를 단순한 Claude Code/Codex류의 “AI 터미널”이 아니라 프로젝트 개발 워크플로우 시스템으로 사용할 수 있습니다. Kiro 공식 문서도 CLI의 핵심 능력으로 Steering, Hooks, MCP, Custom Agents, Skills, Sub-agents, Models, Permissions 등을 같은 기반 기능으로 설명하고 있습니다. (Kiro)

이것만 외워도 됩니다

# 시작
kiro-cli

# 도움말
/guide

# 파일 지정
@src/auth.ts

# 계획
Shift+Tab

# 대형 기능
/spec new feature-name
/spec run feature-name

# 자율 반복
/goal --max 10 목표 + 완료조건

# Context
/context show

# 모델
/model

# Agent
/agent list
/agent swap agent-name

# 세션
/chat new
/chat resume

# 되돌리기
/rewind

# Context 압축
/compact

# 권한
/tools

# 비용 확인
/usage

# Shell
!npm test

이 정도가 Kiro CLI 입문 시 실제로 먼저 익힐 80~90%의 기능이라고 보면 됩니다. 특히 Kiro 특유의 기능을 하나만 꼽는다면 /spec, 그리고 최근 CLI에서 실전성이 높은 기능을 꼽는다면 /goal입니다. (Kiro)

Kiro CLI 공식 문서
Kiro CLI Slash Commands

시니어 엔지니어에서 스태프 엔지니어로 성장

행복한 수지아빠 — Tue, 25 Aug 2026 12:12:07 +0900

시니어 엔지니어에서 스태프 엔지니어(Staff Engineer)로 역할이 확장될 때 가장 크게 달라지는 점 중 하나는 주어진 문제를 잘 푸는 것만으로는 충분하지 않다는 것이다.

스태프 레벨에서는 한 단계 더 나아가야 한다.

우리 팀과 조직이 지금 무엇을 해결해야 하는가?

Lalit Maganti가 자신의 글 How I Find Problems to Solve as a Staff Engineer에서 설명하는 핵심도 바로 여기에 있다.

그가 강조하는 방식은 의외로 단순하다.

회의실에 앉아 억지로 “전략적인 아이디어”를 만들어내는 것이 아니다.

조직에서 매일 발생하는 문제를 지속적으로 관찰하고, 충분한 시간 동안 축적한 뒤, 서로 다른 문제 사이에서 공통된 구조(Common Shape)를 발견하는 것이다.

1. 전략은 빈 문서에서 시작되지 않는다

많은 엔지니어가 스태프 엔지니어가 되면 일정 시간을 따로 확보해 다음과 같은 질문을 고민해야 한다고 생각한다.

우리 조직의 가장 중요한 문제는 무엇인가?
다음 분기에 무엇을 만들어야 하는가?
어떤 프로젝트를 제안해야 하는가?

하지만 Maganti는 이런 방식으로 좋은 문제를 찾는 경우가 거의 없다고 말한다.

대신 자신을 스펀지처럼 만든다.

일상적인 업무 속에서 흘러다니는 정보를 계속 흡수한다.

예를 들어 다음과 같은 곳이다.

회의
Slack이나 사내 채팅
이메일
발표
장애 대응
버그 분석
다른 팀의 불만
개발자가 사용하는 우회 방법
반복적으로 발생하는 운영 문제

처음 들었을 때는 별것 아닌 문제처럼 보일 수 있다.

하지만 바로 해결하려 하지 않고 머릿속에 남겨두면 시간이 지나면서 일부 문제는 사라지고, 일부 문제는 다른 문제와 연결되기 시작한다.

그리고 어느 순간 이런 질문을 할 수 있게 된다.

“이 문제들이 사실은 같은 원인에서 발생하는 것 아닐까?”

스태프 엔지니어의 문제 발견 능력은 여기서 시작된다.

2. 요청(Request)이 아니라 문제(Problem)를 수집한다

사용자는 자신의 문제를 항상 정확하게 설명하지 않는다.

대부분은 문제 대신 해결책을 요청한다.

예를 들어 사용자가 이렇게 말할 수 있다.

“이 버튼을 화면 위쪽에 고정할 수 있게 해주세요.”

이때 그대로 기능 요구사항으로 받아들이면 다음과 같은 구현이 시작된다.

Request
↓
버튼 고정 기능
↓
개발
↓
배포

하지만 스태프 엔지니어는 한 단계 더 들어간다.

Request
↓
왜 필요한가?
↓
어떤 작업을 하려고 하는가?
↓
현재 방식은 왜 불편한가?
↓
다른 팀도 같은 문제가 있는가?
↓
Root Problem

질문도 달라진다.

“왜 이 기능이 필요한가요?”

“지금은 이 작업을 어떻게 하고 있나요?”

“이 기능이 생기면 어떤 문제가 해결되나요?”

“기존 기능으로는 어느 정도까지 해결할 수 있나요?”

요청을 구현하는 것과 문제를 이해하는 것은 완전히 다른 활동이다.

스태프 엔지니어에게 더 중요한 것은 후자다.

3. 직접 워크플로를 관찰한다

문제가 중요해 보이면 Maganti는 단순히 인터뷰만 하지 않는다.

실제 사용자가 문제를 겪는 과정을 직접 본다.

예를 들어 개발팀이 특정 디버깅 문제를 이야기한다면 옆에 앉아서 다음 과정을 확인한다.

Bug 발생
↓
로그 검색
↓
Trace 분석
↓
특정 데이터 찾기
↓
도구 설정 변경
↓
반복 작업
↓
원인 발견

가능하면 자신도 같은 버그를 직접 분석해 본다.

이런 관찰이 중요한 이유는 사용자가 말한 문제와 실제 문제가 다를 수 있기 때문이다.

사용자는

“필터 기능이 필요합니다.”

라고 말하지만 실제로 관찰해 보면 필요한 것은

“매번 같은 분석 환경을 다시 만드는 작업을 없애는 것”

일 수도 있다.

즉,

Requested Solution ≠ Actual Need

일 가능성이 상당히 높다.

4. 조직을 넓게 보는 사람에게서 신호를 얻는다

자신이 경험한 문제만 관찰해서는 조직 전체의 패턴을 발견하기 어렵다.

그래서 Maganti는 다음과 같은 사람들과 의도적으로 이야기한다고 설명한다.

핵심 시스템 담당자
여러 팀을 지원하는 엔지니어
플랫폼 엔지니어
인프라 엔지니어
downstream 시스템을 잘 아는 사람
여러 조직의 문제를 반복해서 접하는 사람

이들은 일종의 Problem Router 역할을 한다.

한 팀에서는

Problem A

로 보였던 것이 다른 팀에서는

Problem B

처럼 나타날 수 있다.

하지만 여러 팀을 보는 사람은 이미 이렇게 인식하고 있을 수 있다.

Team A → Problem A ┐
Team B → Problem B ├→ Root Problem X
Team C → Problem C ┘

스태프 엔지니어에게 조직 내 네트워크가 중요한 이유도 단순히 정치적 영향력을 얻기 위해서가 아니다.

더 많은 문제 신호에 접근하기 위해서다.

5. 문제를 바로 프로젝트로 만들지 않는다

여기서 중요한 원칙이 하나 나온다.

문제를 충분히 쌓이게 둔다.

Maganti는 과거 특정 팀의 요청에 너무 빨리 반응했다가 실패했던 경험을 소개한다.

어떤 팀이 특정 기능을 강하게 원했다.

그래서 기능을 만들었다.

하지만 정작 배포했을 때 거의 사용하지 않았다.

그 사이 팀의 우선순위가 바뀌었거나, 애초에 일회성 조사 때문에 필요했던 기능이었기 때문이다.

이 경험에서 중요한 구분이 나온다.

요청의 강도 ≠ 문제의 중요도

누군가 매우 적극적으로 요구한다고 해서 반드시 중요한 문제는 아니다.

그래서 문제를 처음 발견했을 때 바로 개발 프로젝트로 만들지 않는다.

대신 일종의 Problem Backlog에 넣어둔다.

6. 문제에도 증거가 누적되어야 한다

시간이 지나면서 같은 문제가 다시 나타나는지 본다.

예를 들어 처음에는 이렇게 보인다.

Team A → Problem A

몇 달 뒤 다른 팀에서도 나타난다.

Team A → Problem A
Team B → Problem A

다른 형태로 또 나타난다.

Team C → Problem B

조금 더 분석해 보면 사실 이런 구조일 수 있다.

Problem A ┐
Problem A ├→ Root Problem X
Problem B ┘

이때부터 문제의 중요도가 올라간다.

즉 문제의 우선순위는 단순한 목소리의 크기가 아니라 증거의 누적으로 결정된다.

이를 간단하게 모델링하면 다음과 같이 생각할 수도 있다.

Problem Priority
=
Frequency
× Number of Teams
× Severity
× Strategic Relevance

정확한 공식이 중요한 것이 아니다.

핵심은 문제를 처음 발견한 순간보다 반복해서 발견되는 패턴을 중요하게 보는 것이다.

7. 가장 중요한 순간: Common Shape 찾기

Maganti가 설명하는 과정에서 가장 중요한 단계가 있다.

여러 문제의 공통된 형태를 발견하는 것

Perfetto 사례가 이를 잘 보여준다.

Perfetto는 시스템의 동작 기록을 타임라인으로 분석하는 성능 디버깅 도구다.

여러 팀이 다음과 같은 기능을 요청했다.

Team A
→ 특정 Track을 항상 위에 고정하고 싶다.

Team B
→ 다른 Track을 고정하고 싶다.

Team C
→ 특정 위치로 자동 Zoom하고 싶다.

Team D
→ 특정 Aggregation을 자동으로 보고 싶다.

Team E
→ Bookmarklet으로 직접 자동화하고 있다.

겉으로 보면 모두 다른 기능이다.

그래서 하나씩 대응하면 이런 제품이 된다.

Feature A
Feature B
Feature C
Feature D
Feature E
...

하지만 충분히 문제를 쌓아놓고 보면 공통점이 나타난다.

각 팀이 원한 것은 개별 기능이 아니었다.

각자의 업무 방식에 맞게 Perfetto를 개인화하고 확장할 수 있는 능력이었다.

즉 문제의 구조가 바뀐다.

Track 고정 ┐
Auto Zoom  │
Aggregation├→ UI 확장성
Automation │
Bookmarklet┘

이것이 Common Shape다.

8. 좋은 플랫폼은 기능을 대신 만들어주지 않는다

이 통찰은 플랫폼 엔지니어링에서 특히 중요하다.

첫 번째 접근은 다음과 같다.

Team A 요청 → Platform Team 개발
Team B 요청 → Platform Team 개발
Team C 요청 → Platform Team 개발
Team D 요청 → Platform Team 개발

이 구조에서는 플랫폼 팀이 병목이 된다.

요청이 늘어날수록 유지보수 비용도 계속 증가한다.

반면 공통 문제를 발견하면 구조가 달라진다.

Team A ┐
Team B │
Team C ├→ Extension Platform
Team D │
Team E ┘

플랫폼팀이 모든 기능을 구현하는 대신 다른 팀이 자신의 요구를 해결할 수 있는 Primitive를 제공한다.

Maganti가 Perfetto에서 도달한 방향도 이런 형태였다.

글에 따르면 그는 이후 UI 동작을 자동화할 수 있는 Macros와 이를 팀 간 공유할 수 있는 Extension Servers를 설계했다.

즉,

Build Features

에서

Build Capability

로 문제의 추상화 수준이 올라간 것이다.

이 차이는 매우 크다.

9. 그러나 ‘멋진 추상화’는 증거가 아니다

여기서 위험한 함정이 하나 있다.

엔지니어는 우아한 설계를 좋아한다.

여러 문제를 하나의 구조로 설명할 수 있는 순간 이런 생각이 들기 쉽다.

“찾았다.”

하지만 Maganti는 경고한다.

공통된 구조는 어디까지나 가설이다.

즉,

Elegant Architecture ≠ Correct Problem

이다.

그가 소개한 또 다른 Perfetto 사례에서는 대용량 trace 공유 문제와 반복 query 문제를 하나의 투명한 캐시 시스템으로 해결하려 했다.

처음에는 두 문제를 하나로 해결하는 매우 우아한 설계처럼 보였다.

하지만 RFC와 프로토타입을 만들면서 실제로는 서로 다른 문제라는 사실이 드러났다.

결국 글에 따르면 해결책은 분리됐다.

Repeated Query
→ Warm Session

Large Trace Reopen
→ Streaming Table Export

이 사례에서 중요한 것은 추상화를 사랑하지 않는 태도다.

엔지니어가 만든 개념보다 실제 문제가 더 중요하다.

10. 구현 전에 Pressure Test 한다

Common Shape을 발견했다고 바로 개발하지 않는다.

다음 단계는 가설 검증이다.

Maganti는 상황에 따라 세 가지 방식으로 접근한다고 설명한다.

① 작고 안전한 문제

바로 구현한다.

Low Risk
+
Clear Value
↓
Ship

② 불확실한 문제

버려도 되는 프로토타입을 만든다.

Hypothesis
↓
Throwaway Prototype
↓
Feedback
↓
Technical Risk
↓
Decision

프로토타입의 목적은 제품을 만드는 것이 아니다.

틀렸다는 사실을 싸게 발견하는 것이다.

③ 크지만 확신이 높은 문제

RFC, 설계 검토, 조직 설득까지 들어간다.

Problem
↓
Evidence
↓
Proposal
↓
RFC
↓
1:1
↓
Presentation
↓
Feedback
↓
Refinement
↓
Implementation

스태프 엔지니어의 중요한 역할 중 하나가 바로 이 단계다.

11. 스스로의 아이디어도 설득해야 한다

Pressure Test의 목적은 다른 사람을 설득하는 것만이 아니다.

자신도 설득해야 한다.

다음 질문을 계속 던져야 한다.

이 문제가 정말 중요한가?

여러 팀에게 발생하는가?

기존 도구로 해결할 수 없는가?

우리가 해결해야 하는 문제인가?

기술적으로 가능한가?

유지보수 비용은 감당할 수 있는가?

지금 해결해야 하는가?

그 결과 프로젝트를 포기할 수도 있다.

그것은 실패가 아니다.

오히려 큰 시스템을 만들기 전에 잘못된 가설을 제거한 것이다.

12. 타이밍이 틀렸다면 문제를 버리지 않는다

좋은 아이디어라도 조직의 현재 우선순위와 맞지 않을 수 있다.

이 경우 바로 실행하지 않고 보관한다.

Good Problem
+
Wrong Timing
↓
Park

그리고 환경이 바뀌면 다시 꺼낸다.

Org Priority Change
↓
Existing Problem Evidence
↓
Ready Proposal
↓
Fast Execution

이것은 스태프 레벨에서 상당히 중요한 능력이다.

항상 새로운 아이디어를 만드는 것이 아니라 이미 충분히 연구된 문제를 적절한 순간에 실행하는 것이다.

13. 반드시 자신이 구현할 필요는 없다

스태프 엔지니어의 영향력은 코드량으로 측정되지 않는다.

문제를 발견하고 구조화한 뒤 다른 팀이 구현하게 만들 수도 있다.

Problem Discovery
↓
Problem Framing
↓
Solution Direction
↓
Org Alignment
↓
Another Engineer Implements

이 경우에도 상당한 기술적 영향력을 만들어낼 수 있다.

스태프 엔지니어의 역할은

I built X

에서 점차

X became the right thing for the organization to build

로 확대된다.

14. 문제 해결은 새로운 문제를 가져오는 플라이휠을 만든다

이 과정에는 흥미로운 네트워크 효과가 있다.

누군가의 문제를 진지하게 듣고 실제로 해결해 주면 사람들이 기억한다.

그러면 다음번에는 문제가 더 일찍 공유된다.

문제 발견
↓
좋은 질문
↓
문제 해결
↓
신뢰 증가
↓
더 많은 문제 공유
↓
조직 가시성 증가
↓
더 좋은 문제 발견

즉 하나의 Problem Discovery Flywheel이 만들어진다.

Listen
  ↓
Understand
  ↓
Solve
  ↓
Trust
  ↓
More Signals
  ↓
Better Patterns
  ↓
Better Problems
  ↺

경력이 올라갈수록 스태프 엔지니어가 중요한 문제를 더 빨리 발견하는 이유도 단순히 경험이 많기 때문만은 아니다.

조직 안에서 문제 신호가 그 사람에게 모이기 시작하기 때문이다.

15. Staff Engineer의 핵심 루프

전체 내용을 하나의 루프로 압축하면 다음과 같다.

① Listen
조직의 문제를 듣는다
        ↓
② Dig
요청 뒤의 실제 문제를 파고든다
        ↓
③ Observe
실제 워크플로를 본다
        ↓
④ Accumulate
문제를 바로 해결하지 않고 축적한다
        ↓
⑤ Connect
반복되는 문제 사이의 연결을 찾는다
        ↓
⑥ Abstract
Common Shape을 발견한다
        ↓
⑦ Pressure Test
인터뷰·RFC·Prototype으로 검증한다
        ↓
⑧ Build / Park / Kill
구현하거나 보류하거나 폐기한다
        ↓
⑨ Earn Trust
문제를 해결하면서 신뢰를 만든다
        ↓
⑩ More Signals
더 많은 문제 정보가 들어온다
        ↺

이 루프가 반복될수록 개인의 영향력은 커진다.

16. Senior와 Staff의 차이

이 글의 관점에서 Senior Engineer와 Staff Engineer의 차이를 단순화하면 다음과 같이 볼 수 있다.

Senior EngineerStaff Engineer

어려운 문제를 해결한다	어떤 문제를 해결해야 하는지 찾는다
주어진 프로젝트를 성공시킨다	프로젝트 자체를 만든다
요구사항을 구현한다	요구사항 뒤의 문제를 찾는다
한 팀의 문제를 본다	여러 팀의 패턴을 본다
Feature를 만든다	Capability를 만든다
Implementation 중심	Problem Framing 중심
프로젝트 영향	조직 영향

물론 실제 조직마다 역할 정의는 다르다.

특히 Maganti 자신도 글에서 자신의 경험이 Google과 같은 대규모 조직의 인프라·개발자 도구 팀처럼 엔지니어의 bottom-up 자율성이 큰 환경에 기반한다고 전제한다.

따라서 모든 회사에서 동일한 방식으로 적용된다고 볼 수는 없다.

17. 이 접근법을 실제 업무 시스템으로 만들면

이 방법은 개인의 직관에만 의존할 필요가 없다.

간단한 Problem Discovery System으로 구조화할 수 있다.

예를 들어 문제를 발견할 때 다음 정보를 기록한다.

Problem
 ├─ Source
 ├─ Team
 ├─ Context
 ├─ Requested Solution
 ├─ Actual Problem
 ├─ Frequency
 ├─ Severity
 ├─ Workaround
 ├─ Similar Problems
 ├─ Evidence
 └─ Status

그리고 상태를 관리한다.

Observed
↓
Repeated
↓
Pattern Found
↓
Investigating
↓
Validated
↓
Proposed
↓
Building
↓
Solved

핵심은 아이디어 관리가 아니라 문제 관리다.

일반적인 아이디어 백로그가

What should we build?

을 기록한다면,

Problem Backlog는

What keeps hurting people?

을 기록한다.

제품팀이나 플랫폼팀이라면 후자가 훨씬 강력한 자산이 될 수 있다.

결론

이 글에서 가장 중요한 메시지는 “스태프 엔지니어는 전략 회의를 많이 해야 한다”가 아니다.

오히려 반대에 가깝다.

좋은 전략적 문제는 일상적인 업무와 분리된 곳에서 갑자기 등장하지 않는다.

사람들의 불편
+
반복되는 작업
+
우회 방법
+
여러 팀의 요청
+
기술적 제약
+
시간

이것들이 충분히 축적될 때 중요한 패턴이 보이기 시작한다.

그리고 스태프 엔지니어의 역할은 그 수많은 신호 속에서

“서로 다른 문제처럼 보이지만 사실 같은 문제다.”

라는 순간을 발견하는 것이다.

결국 스태프 엔지니어의 핵심 경쟁력은 단순히 더 어려운 코드를 작성하는 능력만이 아니다.

문제를 수집하고, 문제를 기다리고, 문제를 연결하고, 올바른 추상화 수준에서 문제를 다시 정의하는 능력.

그 능력이 개인의 기술적 영향력을 팀에서 조직으로 확장시킨다.

AI 애플리케이션을 잘 만드는 개발자는 무엇이 다른가

행복한 수지아빠 — Mon, 24 Aug 2026 11:58:57 +0900

Andrew Ng의 AI Engineering Skills Map ① — Building and Deploying AI Applications

AI 애플리케이션 개발은 기존 소프트웨어 개발과 상당히 다릅니다.

전통적인 프로그램에서는 같은 입력을 넣으면 대부분 예상 가능한 결과가 나옵니다.

하지만 LLM이나 머신러닝 모델은 그렇지 않습니다.

같은 프롬프트를 사용하더라도 답변이 달라질 수 있고, 새로운 데이터에 대해 어떤 결과가 나올지 완벽하게 예측하기도 어렵습니다.

그래서 AI 엔지니어링에서 중요한 것은 단순히 LLM API를 호출하는 능력이 아닙니다.

예측하기 어려운 AI 컴포넌트를 이용해 신뢰할 수 있는 시스템을 만드는 능력

Andrew Ng는 이를 위해 필요한 역량을 다음 6가지로 정리합니다.

LLM Foundations
Grounding Models with Data
Building Agentic Systems
Evaluation-Driven Development
Operating in Production
Machine Learning Foundations

하나씩 살펴보겠습니다.

1. LLM Foundations

LLM이 어떻게 동작하는지 이해하기

LLM을 제대로 활용하려면 먼저 모델의 기본 동작을 이해해야 합니다.

단순히

"GPT API를 호출할 줄 안다."

정도로는 부족합니다.

최소한 다음 개념을 이해해야 합니다.

Tokenization
Context Window
Sampling
Reasoning
Knowledge Cutoff
Cache
Tool Calling
Multimodal Model
Fine-tuning
Self-hosting

예를 들어 모델에게 매우 긴 문서를 통째로 Context Window에 넣을 수도 있습니다.

하지만 항상 좋은 선택은 아닙니다.

Context가 길어질수록

비용이 증가하고
응답 시간이 늘어나며
중요한 정보가 묻힐 수 있습니다.

따라서 개발자는 판단해야 합니다.

전체 데이터를 Context에 넣을 것인가?

아니면

필요한 데이터만 검색해서 가져오게 할 것인가?

이런 판단을 하기 위해 LLM의 기본 구조를 이해해야 합니다.

2. Grounding Models with Data

AI에게 좋은 데이터를 제공하는 방법

LLM의 성능은 모델 자체만으로 결정되지 않습니다.

AI에게 어떤 Context를 제공하느냐가 매우 중요합니다.

초기 LLM 애플리케이션에서는 주로 RAG + Vector Search 구조가 많이 사용되었습니다.

대표적인 구조는 다음과 같습니다.

사용자 질문
↓
Embedding
↓
Vector Search
↓
관련 문서 검색
↓
LLM Context에 삽입
↓
답변 생성

하지만 지금의 Grounding 기술은 훨씬 다양해졌습니다.

데이터 특성에 따라 다른 구조를 선택할 수 있습니다.

Vector Database

문서나 자연어 검색에 적합합니다.

예:

사내 문서
매뉴얼
고객 문의
기술 문서

Knowledge Graph

개체와 관계가 중요한 데이터에 적합합니다.

예:

사용자 → 회사 → 프로젝트 → 제품

처럼 관계 중심의 정보를 표현할 수 있습니다.

Structured Data

CRM이나 ERP 같은 구조화된 데이터는 SQL이나 Semantic Layer를 사용할 수 있습니다.

예:

고객 정보
주문 기록
재고
매출
사용자 활동

여기서 중요한 질문은 이것입니다.

이 데이터를 AI에게 어떤 방식으로 제공하는 것이 가장 좋은가?

그리고 데이터를 한 번 연결했다고 끝나는 것도 아닙니다.

PDF, HTML, 이미지, 문서 등을 AI가 사용할 수 있는 형태로 변환하고 지속적으로 업데이트해야 합니다.

즉 AI 시대에는 Data Engineering과 Context Engineering의 경계도 점점 가까워지고 있습니다.

3. Building Agentic Systems

AI에게 일을 맡기는 시스템 만들기

단순한 LLM 애플리케이션은 이런 구조입니다.

사용자
→ Prompt
→ LLM
→ Answer

하지만 Agentic System은 다릅니다.

예를 들어 리서치 에이전트라면 다음과 같이 움직일 수 있습니다.

질문 분석
↓
검색
↓
자료 읽기
↓
추가 검색 결정
↓
정보 정리
↓
초안 작성
↓
검증
↓
최종 답변

여기서 LLM은 단순히 답변을 생성하는 것이 아니라

다음에 무엇을 해야 할지 결정합니다.

Andrew Ng는 Agentic System을 크게 두 종류로 볼 수 있다고 설명합니다.

Workflow

미리 정해진 순서대로 실행합니다.

예:

Research → Summarize → Write → Review

Agent Loop

AI가 상황에 따라 다음 행동을 스스로 선택합니다.

예:

Think
→ Tool
→ Observe
→ Think
→ Tool
→ Observe
→ Answer

Agent를 만들 때 필요한 판단

Agentic System을 설계할 때는 의외로 많은 결정을 해야 합니다.

예를 들어 다음과 같습니다.

어떤 작업을 연결할 것인가?

A → B → C

어떤 작업을 병렬 처리할 것인가?

예:

Search A

Search B

Search C

세 검색이 서로 의존하지 않는다면 동시에 실행할 수 있습니다.

어떤 작업을 코드로 처리할 것인가?

모든 것을 LLM에게 맡길 필요는 없습니다.

정확한 계산이나 규칙 기반 작업은 일반 코드가 더 적합할 수 있습니다.

어떤 Tool을 제공할 것인가?

Agent가 사용할 수 있는 도구는 다양합니다.

Web Search
Database
API
MCP
CLI
Browser
Sandbox
Python

Memory와 Context 관리

Agent가 오랫동안 작업하면 Context가 계속 커집니다.

따라서 다음도 설계해야 합니다.

Short-term Memory
Long-term Memory
Session Memory
Context Compression
Summary
Retrieval

특히 긴 작업에서는 모든 대화를 계속 Context에 넣는 방식보다 필요한 정보만 유지하거나 다시 검색하는 구조가 중요합니다.

언제 Multi-Agent를 사용할 것인가?

모든 문제에 Multi-Agent가 필요한 것은 아닙니다.

간단한 문제는 Single Agent가 더 효율적일 수 있습니다.

하지만 역할이 명확히 나뉘는 작업에서는 Multi-Agent 구조를 고려할 수 있습니다.

예를 들면 콘텐츠 제작 시스템을 이렇게 나눌 수 있습니다.

Research Agent

자료 조사

↓

Writer Agent

초안 작성

↓

Fact Checker

사실 확인

↓

Editor Agent

문장 개선

↓

Publisher Agent

게시 형식 변환

이것이 바로 Agent Orchestration입니다.

4. Evaluation-Driven Development

AI 개발에서 가장 중요한 기술 중 하나

Andrew Ng는 AI 시스템 개발에서 중요한 역량으로 Eval과 Error Analysis를 특히 강조합니다.

AI 개발에서 흔히 발생하는 문제는 이것입니다.

프롬프트를 수정합니다.

결과를 봅니다.

괜찮아 보입니다.

다시 수정합니다.

하지만 이렇게 개발하면 개선이 실제로 일어나고 있는지 알기 어렵습니다.

따라서 AI 시스템에서는 다음 루프가 필요합니다.

Build
↓
Run
↓
Evaluate
↓
Error Analysis
↓
Improve
↓
Run Again

이것을 Evaluation-Driven Development라고 볼 수 있습니다.

Eval은 어떻게 할까?

평가 방법은 여러 가지가 있습니다.

1. Deterministic Evaluation

코드로 명확하게 검사합니다.

예:

JSON 형식이 맞는가?
필수 필드가 있는가?
숫자 범위가 맞는가?
URL 형식이 올바른가?

2. LLM-as-a-Judge

다른 LLM에게 결과를 평가하게 합니다.

예:

이 답변이 사용자의 질문에 정확히 답했는지
1~5점으로 평가하세요.

3. Human Evaluation

사람이 직접 평가합니다.

특히 다음과 같은 요소는 사람 평가가 중요할 수 있습니다.

자연스러움
유용성
브랜드 톤
창의성
사용자 만족도

중요한 것은 Eval 자체도 평가해야 한다는 것

Eval을 만들었다고 끝나는 것이 아닙니다.

Eval 자체가 실제 품질을 제대로 측정하고 있는지도 확인해야 합니다.

예를 들어 LLM Judge가 좋은 답변과 나쁜 답변을 제대로 구분하지 못한다면 평가 시스템 역시 개선해야 합니다.

따라서 실제 AI 시스템은 다음과 같이 움직입니다.

AI System

↓

Eval System

↓

Eval의 정확성 검증

↓

Eval 개선

↓

AI System 개선

즉 평가 시스템 역시 하나의 제품입니다.

5. Operating in Production

AI를 실제 서비스로 운영하기

Prototype과 Production은 완전히 다른 문제입니다.

Demo에서는 잘 작동하던 AI가 실제 사용자에게 공개되면 예상하지 못했던 문제가 발생합니다.

예를 들어

이상한 질문
매우 긴 입력
Prompt Injection
잘못된 검색 결과
API 장애
모델 업데이트
비용 폭증
응답 지연

등이 나타납니다.

따라서 Production에서는 Observability가 중요합니다.

무엇을 관찰해야 할까?

대표적으로 다음을 추적할 수 있습니다.

Quality

답변 품질

Latency

응답 시간

Cost

Token 비용

Error

실패율

Tool Usage

Tool 호출 성공률

Retrieval

검색 정확도

Security

Prompt Injection이나 데이터 유출 위험

AI 시스템에는 Drift도 존재한다

서비스를 운영하다 보면 사용자의 질문 유형이 달라질 수도 있습니다.

모델이 업데이트될 수도 있습니다.

데이터베이스 내용도 바뀝니다.

따라서 시간이 지나면서 기존 Eval 성능이 떨어질 수 있습니다.

이 때문에

Monitoring + Regression Test

가 필요합니다.

새로운 모델이나 프롬프트를 적용하기 전에 기존 Eval Dataset을 다시 실행해서 성능이 떨어지지 않았는지 확인하는 것입니다.

비용과 Latency도 AI Engineering이다

AI 서비스를 대규모로 운영하면 작은 비용 차이가 큰 차이를 만듭니다.

예를 들어 한 요청에 1센트가 든다고 가정해 보겠습니다.

하루 100만 요청이면

$10,000 / day

가 됩니다.

따라서 Production에서는 모델 정확도만 볼 수 없습니다.

다음 요소를 함께 고려해야 합니다.

Quality

Cost

Latency

이 세 가지 사이의 트레이드오프가 존재합니다.

이를 개선하기 위해 다음과 같은 방법을 사용할 수 있습니다.

Smaller Model
Model Routing
Caching
Distillation
Fine-tuning
Prompt Optimization
Context Reduction
Workflow Simplification

6. Machine Learning Foundations

LLM 시대에도 ML 기본기가 필요한 이유

LLM이 등장하면서 Machine Learning을 공부할 필요가 없어졌다고 생각할 수도 있습니다.

하지만 Andrew Ng는 반대로 이야기합니다.

좋은 LLM 엔지니어들은 대부분 Machine Learning과 Deep Learning에 대한 기본적인 이해를 가지고 있다는 것입니다.

특히 다음 개념은 여전히 중요합니다.

Supervised Learning
Reinforcement Learning
Training / Validation / Test
Bias
Variance
Overfitting
Error Analysis
Data Engineering
Accuracy
Precision / Recall

그 이유는 LLM도 결국 확률적 Machine Learning 시스템이기 때문입니다.

Bias와 Variance 사고방식

예를 들어 AI 시스템의 성능이 낮을 때 단순히

"프롬프트를 더 잘 써야겠다."

라고 판단해서는 안 됩니다.

문제의 원인을 분석해야 합니다.

모델 문제인가?

모델 능력이 부족한가?

데이터 문제인가?

Context가 부족한가?

Retrieval 문제인가?

잘못된 문서를 검색하는가?

Prompt 문제인가?

지시가 명확하지 않은가?

Tool 문제인가?

Agent가 잘못된 Tool을 사용하는가?

Evaluation 문제인가?

평가 기준 자체가 잘못되어 있는가?

이것이 바로 머신러닝에서 오랫동안 사용해 온 Error Analysis 사고방식입니다.

결국 AI Engineering은 반복의 기술이다

AI 시스템을 만드는 과정을 한 줄로 표현하면 다음과 같습니다.

Build → Measure → Analyze → Improve → Repeat

기존 소프트웨어에서는 설계를 먼저 충분히 한 뒤 구현하는 방식이 비교적 잘 작동했습니다.

하지만 AI 시스템은 결과가 불확실하기 때문에 실제로 만들어 보고 결과를 확인하면서 다음 행동을 결정해야 하는 경우가 많습니다.

그래서 AI 엔지니어에게 중요한 능력은

첫 번째 버전을 완벽하게 만드는 능력

보다

결과를 보고 다음 실험을 정확하게 결정하는 능력

에 가깝습니다.

6가지 역량을 하나의 시스템으로 보면

Andrew Ng가 설명한 6가지 역량은 서로 독립적이지 않습니다.

다음과 같이 연결됩니다.

LLM Foundations

모델을 이해한다.

↓

Grounding

좋은 Context를 제공한다.

↓

Agentic Systems

AI가 Tool을 사용하며 작업하도록 만든다.

↓

Evaluation

결과를 측정한다.

↓

Production

실제 환경에서 관찰하고 운영한다.

↓

Machine Learning Foundations

문제의 원인을 분석하고 개선한다.

그리고 다시 처음으로 돌아갑니다.

이 구조는 결국 하나의 거대한 Feedback Loop입니다.

실전 학습 로드맵으로 바꾼다면

이 내용을 공부 순서로 바꾸면 다음과 같이 구성할 수 있습니다.

STEP 1. LLM 기본기

Token
Context Window
Prompt
Structured Output
Tool Calling
Multimodal

↓

STEP 2. Grounding

Embedding
Vector DB
RAG
Hybrid Search
Knowledge Graph
Structured Data

↓

STEP 3. Agent

Tool
Workflow
Agent Loop
Memory
MCP
Multi-Agent

↓

STEP 4. Evaluation

Golden Dataset
Deterministic Eval
LLM Judge
Human Eval
Error Analysis

↓

STEP 5. Production

Logging
Tracing
Monitoring
Guardrails
CI/CD
Cost Optimization

↓

STEP 6. Machine Learning

Supervised Learning
Deep Learning
Bias / Variance
Error Analysis
Data Engineering

앞으로 AI 개발자의 핵심 경쟁력

AI 개발에서 중요한 것은 가장 최신 모델을 가장 빨리 사용하는 것만은 아닙니다.

모델은 계속 바뀝니다.

GPT, Claude, Gemini와 같은 모델뿐만 아니라 새로운 모델과 Agent Framework도 계속 등장할 것입니다.

하지만 그 위에서 반복되는 핵심 질문은 크게 달라지지 않습니다.

어떤 모델을 사용할 것인가?

어떤 데이터를 Context로 제공할 것인가?

어떤 Tool을 연결할 것인가?

어떤 Workflow를 구성할 것인가?

결과가 좋은지 어떻게 평가할 것인가?

실패 원인은 무엇인가?

Production에서 비용과 Latency를 어떻게 관리할 것인가?

이 질문에 체계적으로 답할 수 있는 사람이 AI Engineering을 잘하는 개발자에 가까워질 것입니다.

정리

Andrew Ng가 제시한 Building and Deploying AI Applications의 핵심 역량은 다음 6가지입니다.

1. LLM Foundations

LLM의 동작 원리를 이해하고 적절한 모델과 기능을 선택하는 능력.

2. Grounding Models with Data

RAG, Vector Search, Knowledge Graph, Structured Data 등을 이용해 모델에 적절한 Context를 제공하는 능력.

3. Building Agentic Systems

Workflow, Agent Loop, Tool, Memory, MCP, Multi-Agent 등을 설계하는 능력.

4. Evaluation-Driven Development

Eval과 Error Analysis를 이용해 AI 시스템을 체계적으로 개선하는 능력.

5. Operating in Production

Observability, Security, Cost, Latency, Regression Test 등을 관리하는 능력.

6. Machine Learning Foundations

Bias, Variance, Error Analysis, Data Engineering 등 머신러닝의 기본 원리를 이해하는 능력.

결국 AI Engineering의 핵심은 단순합니다.

신뢰하기 어려운 AI 컴포넌트를 이용해 신뢰할 수 있는 시스템을 만드는 것.

그리고 그 과정은 한 번의 완벽한 설계가 아니라

Build → Eval → Error Analysis → Improve

를 끊임없이 반복하는 과정입니다.

AI 시대에는 코드를 작성하는 능력뿐 아니라 모델, 데이터, Agent, Evaluation, Production을 하나의 시스템으로 설계하는 능력이 개발자의 중요한 경쟁력이 되고 있습니다.

AI 시대 개발자가 반드시 갖춰야 할 4가지 역량

행복한 수지아빠 — Mon, 24 Aug 2026 11:56:07 +0900

Andrew Ng의 「AI Engineering Skills Map」이 말하는 개발자의 새로운 기준

AI가 소프트웨어를 만드는 방식을 완전히 바꾸고 있습니다.

불과 몇 년 전만 해도 개발자의 핵심 역량은 프로그래밍 언어, 프레임워크, 데이터베이스, 서버 아키텍처 등을 얼마나 잘 다루느냐에 집중되어 있었습니다.

하지만 생성형 AI와 코딩 에이전트가 빠르게 발전하면서 상황이 달라졌습니다.

이제 중요한 것은 단순히 코드를 얼마나 잘 작성하는가가 아닙니다.

AI를 이용해 무엇을 만들 것인지 결정하고, AI가 제대로 만들도록 설계하고 검증하는 능력

이 점이 점점 더 중요해지고 있습니다.

Andrew Ng는 최근 **「The AI Engineering Skills Map」**을 공개하면서 앞으로 개발자에게 중요한 AI 엔지니어링 역량을 크게 네 가지로 정리했습니다.

그의 팀은 10,000개 이상의 채용 공고를 분석하고, AI 전문가·채용 담당자·리크루터 인터뷰와 설문조사 등을 종합해 이 역량 지도를 만들었다고 설명합니다.

핵심은 다음 네 가지입니다.

AI 애플리케이션 구축과 배포
소프트웨어 엔지니어링 기본기
코딩 에이전트 활용
무엇을 만들지 결정하는 능력, Shaping the Build

하나씩 살펴보겠습니다.

1. AI 애플리케이션을 만들고 배포하는 능력

Building and Deploying AI Applications

전통적인 소프트웨어와 AI 소프트웨어 사이에는 중요한 차이가 있습니다.

바로 출력의 불확실성입니다.

일반적인 프로그램에서는 동일한 입력과 조건이라면 결과를 어느 정도 예측할 수 있습니다.

하지만 LLM에 프롬프트를 입력하면 매번 조금씩 다른 답이 나올 수 있습니다.

머신러닝 모델 역시 새로운 데이터에 어떤 예측을 내놓을지 완벽하게 미리 알 수 없습니다.

따라서 AI 애플리케이션 개발자는 단순히 API를 호출할 줄 아는 것으로는 부족합니다.

다음과 같은 기술을 이해해야 합니다.

LLM
Prompt Engineering
Context Engineering
RAG
Agentic Workflow
Machine Learning
Deep Learning
AI Evaluation
Error Analysis
Observability
Guardrails

특히 Andrew Ng가 강조하는 것이 Eval과 Error Analysis입니다.

AI 시스템은 이런 구조로 개선됩니다.

AI 실행 → 결과 수집 → 평가 → 오류 분류 → 개선 → 다시 평가

예를 들어 고객 상담 AI가 있다고 생각해 보겠습니다.

단순히

"답변을 잘하도록 프롬프트를 수정한다"

는 방식으로 개발하면 한계가 있습니다.

대신 실제 질문 1,000개를 모아서 다음과 같이 분류할 수 있습니다.

정확한 답변
사실 오류
질문 의도 오해
정보 부족
지나치게 긴 답변
정책 위반
RAG 검색 실패

그리고 각각의 오류 유형이 얼마나 발생하는지 측정합니다.

이때부터 AI 개발은 감각적인 프롬프트 수정이 아니라 데이터 기반 엔지니어링이 됩니다.

2. 소프트웨어 엔지니어링 기본기는 오히려 더 중요해진다

Software Engineering Fundamentals

AI 시대가 되면서 종종 이런 이야기가 나옵니다.

"이제 코딩을 몰라도 AI가 프로그램을 만들어준다."

부분적으로는 맞습니다.

하지만 복잡한 서비스를 개발할수록 오히려 소프트웨어 엔지니어링 기본기가 중요해집니다.

소프트웨어 개발에는 항상 여러 가지 트레이드오프가 존재하기 때문입니다.

예를 들어 시스템을 설계할 때 다음을 동시에 고려해야 합니다.

비용
확장성
안정성
속도
보안
개인정보 보호
유지보수성

AI 코딩 에이전트에게 단순히

"사용자 100만 명이 사용할 서비스를 만들어줘."

라고 요청하는 것과

"읽기 트래픽이 쓰기 트래픽보다 20배 많고, PostgreSQL을 primary datastore로 사용하며 Redis caching을 적용하고 stateless API 서버를 horizontal scaling할 수 있도록 설계해줘."

라고 요청하는 것은 결과가 완전히 다릅니다.

좋은 개발자는 AI에게 정확한 Engineering Context를 제공할 수 있습니다.

이를 위해서는 다음 기본기가 여전히 필요합니다.

시스템 설계

Client / Server 구조
API 설계
Load Balancing
Caching
Queue
Distributed System

데이터베이스

SQL / NoSQL
Index
Transaction
Replication
Partitioning

Backend

Authentication
Authorization
Logging
Error Handling
Background Job

Infrastructure

Docker
Cloud
CI/CD
Monitoring
Scaling

AI가 코드를 만들어줄수록 개발자는 오히려 AI가 내린 기술적 선택이 적절한지 판단할 수 있어야 합니다.

3. Coding Agent를 사용하는 능력

Using Coding Agents

앞으로 개발자의 중요한 역량 중 하나는 단순한 AI 코딩 도구 사용이 아니라 Coding Agent Management가 될 가능성이 큽니다.

코딩 에이전트를 잘 사용하는 개발자는 다음을 이해합니다.

Context 관리

에이전트에게 모든 정보를 한꺼번에 제공한다고 좋은 결과가 나오는 것은 아닙니다.

필요한 정보를 필요한 순간에 제공해야 합니다.

예를 들어 다음을 관리해야 합니다.

프로젝트 구조
Architecture
Coding Convention
API Specification
Database Schema
기존 구현
Test
Constraints

즉,

Prompt Engineering → Context Engineering

으로 중심이 이동합니다.

Planning과 Execution을 분리한다

복잡한 작업을 바로 코딩하도록 요청하는 것보다 다음과 같이 나누는 방법이 효과적입니다.

요구사항 분석
↓
구현 계획
↓
작업 분할
↓
코드 구현
↓
테스트
↓
검증
↓
수정

즉 코딩 에이전트를 단순한 코드 생성기가 아니라 작업을 수행하는 엔지니어처럼 관리하는 것입니다.

Verification Loop를 만들어야 한다

AI가 코드를 작성하는 것보다 더 중요한 것은 코드가 올바른지 확인하는 과정입니다.

예를 들어 다음 루프를 만들 수 있습니다.

Agent

코드 작성

↓

Test

자동 테스트

↓

Verifier

오류 확인

↓

Agent

수정

↓

Test

재검증

이 구조를 만들면 사람이 모든 코드를 일일이 확인하지 않아도 에이전트가 일정 부분 스스로 문제를 수정할 수 있습니다.

4. 이제 개발자는 "무엇을 만들 것인가"까지 결정해야 한다

Shaping the Build

개인적으로 이번 Skills Map에서 가장 중요한 변화라고 볼 수 있는 부분입니다.

예전 개발 프로세스에서는 흔히 역할이 이렇게 나뉘었습니다.

기획자

무엇을 만들지 결정

↓

디자이너

화면 설계

↓

개발자

구현

하지만 AI 코딩 에이전트가 구현 영역을 빠르게 자동화하면서 개발자의 역할이 위쪽으로 이동하고 있습니다.

앞으로는 개발자가 이런 질문에도 답할 수 있어야 합니다.

어떤 문제를 해결해야 하는가?
고객에게 실제 필요한 기능은 무엇인가?
어떤 기능을 제거해도 되는가?
MVP에는 무엇만 넣어야 하는가?
지금 빠르게 만들어야 하는가?
아니면 안정성을 위해 천천히 개발해야 하는가?
어떤 지표로 성공을 판단할 것인가?

즉 개발자에게 Product Sense가 요구됩니다.

개발자의 역할이 바뀌고 있다

기존 개발자의 업무 흐름을 단순화하면 이랬습니다.

Requirement
→ Design
→ Coding
→ Test
→ Deploy

AI 시대에는 조금 다른 구조가 나타납니다.

Problem Discovery
↓
Product Definition
↓
Spec
↓
Agent Orchestration
↓
AI Coding
↓
Automated Evaluation
↓
Human Review
↓
Deployment

여기에서 사람이 담당하는 영역은 점점

Coding

보다

Decision Making + Architecture + Evaluation

쪽으로 이동합니다.

앞으로 중요한 것은 Agent가 아니라 Agent를 관리하는 능력이다

AI 개발 도구는 앞으로 계속 좋아질 것입니다.

하지만 도구 이름 자체를 외우는 것은 장기적인 경쟁력이 되기 어렵습니다.

오늘은 Claude Code를 사용할 수도 있고,

Codex나 Cursor를 사용할 수도 있으며,

내년에는 전혀 다른 Coding Agent가 등장할 수도 있습니다.

더 중요한 것은 그 아래에 있는 공통 원리를 이해하는 것입니다.

예를 들면 다음과 같습니다.

Context Management

에이전트가 필요한 정보를 제공한다.

Task Decomposition

복잡한 문제를 작은 작업으로 나눈다.

Agent Orchestration

여러 에이전트에게 작업을 분배한다.

Verification

테스트와 Eval로 결과를 검증한다.

Feedback Loop

오류를 발견하고 다시 에이전트에게 전달한다.

이 원리를 알고 있다면 사용하는 AI 도구가 달라져도 빠르게 적응할 수 있습니다.

AI Engineering Skills Map을 학습 로드맵으로 바꾸면

Andrew Ng의 네 가지 영역을 실제 공부 순서로 확장하면 다음과 같은 구조를 만들 수 있습니다.

LEVEL 1 — Software Engineering

먼저 개발의 기반을 익힙니다.

Programming
Git
API
Database
Testing
Docker
Cloud
System Design

↓

LEVEL 2 — AI Application

AI 애플리케이션의 핵심 구성 요소를 배웁니다.

LLM API
Structured Output
Tool Calling
Context Engineering
Embedding
Vector Database
RAG
Guardrails

↓

LEVEL 3 — AI Evaluation

AI 시스템을 측정하고 개선하는 방법을 익힙니다.

Dataset
Eval
LLM-as-a-Judge
Error Analysis
Regression Test
Observability

↓

LEVEL 4 — Agent Engineering

하나의 LLM 호출에서 에이전트 시스템으로 확장합니다.

Tool Use
Planning
Memory
Agent Loop
Multi-Agent
Workflow
Human-in-the-Loop

↓

LEVEL 5 — Coding Agent Engineering

AI와 함께 실제 소프트웨어를 개발합니다.

Specification
Context Management
Agent Planning
Code Generation
Test Automation
Verifier
Agent Orchestration

↓

LEVEL 6 — Shaping the Build

마지막 단계에서는 단순 개발을 넘어 제품을 설계합니다.

Problem Discovery
Product Sense
User Interview
MVP
Rapid Prototyping
Business Context
Metrics
Iteration

결국 개발자는 '코드를 만드는 사람'에서 '시스템을 만드는 사람'으로 이동한다

Andrew Ng의 AI Engineering Skills Map에서 중요한 메시지는 AI 기술 몇 가지를 새롭게 배우라는 것만은 아닙니다.

개발자의 역할 자체가 변하고 있다는 것입니다.

과거에는

내가 어떻게 코드를 작성할 것인가?

가 중요한 질문이었다면,

앞으로는

무엇을 만들어야 하는가?

AI에게 어떤 Context를 제공해야 하는가?

어떻게 작업을 분리해야 하는가?

어떻게 결과가 제대로 나왔는지 검증할 것인가?

가 더 중요한 질문이 됩니다.

결국 개발자의 핵심 역량은 다음과 같이 이동하고 있습니다.

Code Writing
→ Context Engineering
→ Agent Orchestration
→ Evaluation
→ Architecture
→ Product Decision

코딩 능력이 사라지는 것이 아니라, 코딩을 포함하는 더 높은 수준의 엔지니어링 능력이 필요해지는 것입니다.

정리

Andrew Ng가 제시한 AI Engineering의 핵심은 네 가지입니다.

① Building and Deploying AI Applications

LLM, RAG, Agent, Eval 등을 활용해 예측하기 어려운 AI 시스템을 측정하고 개선하는 능력.

② Software Engineering Fundamentals

Architecture, Database, Security, Scaling 등 좋은 기술적 판단을 내릴 수 있는 기본기.

③ Using Coding Agents

AI에게 Context를 제공하고 작업을 분할하며 테스트와 검증 루프를 만들어 개발을 자동화하는 능력.

④ Shaping the Build

단순히 주어진 기능을 구현하는 것이 아니라 고객의 문제를 발견하고 제품과 MVP 자체를 설계하는 능력.

그리고 이 네 가지를 관통하는 기반은 하나입니다.

Continuous Learning — 계속 배우고 자신의 개발 방식을 업데이트하는 것.

AI Engineering 시대의 좋은 개발자는 가장 많은 코드를 작성하는 사람이 아닐지도 모릅니다.

문제를 정의하고, 좋은 시스템을 설계하고, AI 에이전트를 지휘하고, 결과를 검증하면서 제품을 끝까지 만들어낼 수 있는 사람.

Andrew Ng의 Skills Map은 개발자의 역할이 그 방향으로 이동하고 있음을 보여주는 하나의 중요한 프레임워크입니다.

DuckDB 2.0, 작은 분석 DB가 서버를 향하기 시작했다

행복한 수지아빠 — Fri, 21 Aug 2026 13:08:51 +0900

파일 하나 열어 분석하던 DuckDB가 이제 PostgreSQL과 S3, 서버의 영역까지 넘보고 있다

데이터 분석을 하다 보면 항상 비슷한 고민을 하게 된다.

CSV 파일 몇 개를 분석하기 위해 데이터베이스 서버를 구축하기에는 너무 무겁다.

그렇다고 Python과 Pandas만으로 처리하기에는 데이터가 커지면서 메모리와 성능이 부담스럽다.

이 사이에서 빠르게 성장한 데이터베이스가 DuckDB다.

DuckDB는 별도의 데이터베이스 서버를 운영하지 않고도 애플리케이션 프로세스 안에서 SQL 분석을 수행할 수 있는 데이터베이스다.

그런데 2026년 가을 출시가 예정된 DuckDB 2.0에서는 이 정체성이 꽤 크게 확장된다.

DuckDB 개발팀은 이번 버전을 설명하면서 이렇게 방향을 잡았다.

지난해가 Lakehouse의 해였다면, 이번 릴리스는 DuckDB가 서버가 되는 해의 시작이다.

DuckDB 2.0은 단순한 성능 업데이트라기보다는 DuckDB가 어디까지 사용될 수 있는지 범위를 넓히는 버전에 가깝다.

v1.5 이후 10,000개 이상의 커밋이 들어갔고, SQL Parser와 Storage Format 같은 내부 구조까지 상당 부분 손봤다.

1. 가장 큰 변화, DuckDB가 서버가 된다

지금까지 DuckDB를 설명할 때 빠지지 않았던 특징이 있다.

In-process Database.

PostgreSQL이나 MySQL처럼 별도 데이터베이스 서버에 접속하는 구조가 아니라 프로그램 안에 DuckDB 엔진을 넣어 사용하는 방식이다.

그런데 DuckDB 2.0부터 여기에 새로운 선택지가 생긴다.

Quack Protocol

DuckDB의 새로운 네트워크 프로토콜인 Quack을 이용하면 DuckDB 데이터베이스를 네트워크를 통해 제공할 수 있다.

서버에서는 대략 다음과 같이 DuckDB를 서비스할 수 있다.

CALL quack_serve(
    token = 'my_token'
);

다른 DuckDB에서는 이 서버에 접속한다.

ATTACH 'quack:server.example.com'
    AS qk (TOKEN 'my_token');

CONNECT qk;

SELECT count(*)
FROM events;

DISCONNECT;

중요한 부분은 SELECT가 클라이언트에서 수행되는 것이 아니라 서버에서 실행되고 결과만 전달된다는 것이다.

DuckDB가 단순히

내 노트북 안에서 Parquet을 빠르게 분석하는 DB

에서

네트워크를 통해 여러 시스템이 접근하는 분석 엔진

으로 확장되기 시작한 셈이다.

2. 더 재미있는 것은 CONNECT다

CONNECT는 DuckDB 서버에만 사용하는 기능이 아니다.

PostgreSQL에도 연결할 수 있다.

CONNECT 'postgres://localhost/mydb';

SELECT count(*)
FROM orders;

DISCONNECT;

여기서 재미있는 점은 DuckDB가 PostgreSQL 테이블 전체를 가져와서 분석하는 것이 아니라는 것이다.

새로운 Remote Pushdown Optimizer가 SQL을 PostgreSQL이나 MySQL 쪽으로 전달해 가능한 연산을 원격 서버에서 수행한다.

구조적으로 보면 이런 그림이 가능해진다.

Application
     │
   DuckDB
     │
 ┌───┼─────────┐
 │   │         │
 ▼   ▼         ▼
S3 PostgreSQL MySQL
 │
Parquet

[Inference] 이렇게 보면 DuckDB가 단순한 데이터 저장소라기보다 여러 데이터 소스를 SQL로 연결하는 경량 분석 계층으로 활용될 가능성이 더 커진다.

3. JSON을 위한 새로운 무기, VARIANT

최근 데이터 시스템에서 JSON을 피하기는 어렵다.

로그도 JSON이고,

API 데이터도 JSON이고,

AI Agent의 결과도 JSON인 경우가 많다.

문제는 JSON이 편리한 대신 분석 효율이 좋지 않은 경우가 많다는 것이다.

DuckDB가 해결책으로 밀고 있는 것이 VARIANT 타입이다.

DuckDB 팀은 이를 사실상

JSON on steroids

라고 설명한다.

VARIANT는 한 컬럼 안에 서로 다른 구조의 데이터를 저장할 수 있다는 점에서는 JSON과 비슷하다.

하지만 문자열 형태의 JSON을 그대로 보관하는 방식이 아니다.

DuckDB가 데이터 안의 공통 구조를 자동으로 찾아 내부적으로 분해해 저장한다.

덕분에 별도의 스키마를 미리 정의하지 않아도 압축과 쿼리 실행 효율을 높일 수 있다.

예를 들어 다음과 같이 사용할 수 있다.

CREATE TABLE events (
    payload VARIANT
);

INSERT INTO events
VALUES (
    '{"user":{"id":42,"tags":["a","b"]}}'
    ::JSON::VARIANT
);

특히 구조가 조금씩 변하는 로그 데이터나 이벤트 스트림 같은 데이터에 어울리는 기능이다.

DuckDB 팀은 v2.0 이후 일반 JSON 타입의 내부 구현을 VARIANT 기반으로 바꾸는 것도 검토하고 있다고 밝혔다. 다만 이는 v2.0 이후 계획이며 확정 일정은 아니다.

4. 드디어 Trigger가 들어왔다

서버형 데이터베이스에 가까워지면서 자연스럽게 추가된 기능도 있다.

바로 Trigger다.

DuckDB 2.0은 다음 기능들을 제공할 예정이다.

BEFORE / AFTER

FOR EACH ROW / FOR EACH STATEMENT

OLD / NEW TABLE

여러 Trigger

RETURNING

DROP TRIGGER

등이다.

예를 들어 데이터가 변경될 때 자동으로 Audit Log를 남길 수 있다.

UPDATE
   │
   ▼
Target Table
   │
 Trigger
   ▼
Audit Table

예전 DuckDB가 단발성 분석 작업 중심이었다면, Trigger는 장시간 동작하는 DuckDB 서비스라는 새로운 사용 방식과 상당히 잘 맞는다.

5. AI 시대에 재미있는 기능, NEAREST JOIN

개인적으로 DuckDB 2.0의 SQL 변화 중 눈에 띄는 것은 NEAREST JOIN이다.

예를 들어 사용자 embedding과 상품 embedding이 있다고 해보자.

SELECT
    q.user_id,
    t.product_id
FROM users q
INNER JOIN products t
APPROX NEAREST 2
BY SIMILARITY
array_cosine_similarity(
    q.embedding,
    t.embedding
);

SQL JOIN 문법 자체로 Top-K Similarity Search를 수행할 수 있다.

기존에는 이런 작업을 위해 별도의 Vector DB나 검색 시스템을 고려해야 하는 경우가 많았다.

물론 이것만으로 DuckDB가 전문 Vector Database를 대체한다고 말할 수는 없다.

하지만 작은 AI 서비스나 로컬 RAG, 데이터 분석 파이프라인처럼

Metadata
+
Embedding
+
Analytics

를 한곳에서 처리하려는 상황에서는 꽤 흥미로운 선택지가 될 수 있다.

6. SQL 자체도 훨씬 강력해졌다

DuckDB 2.0에서는 SQL 기능도 대거 추가된다.

예를 들어 CTE 안에서 DELETE를 실행한 뒤 바로 다른 테이블로 넣을 수 있다.

WITH moved AS MATERIALIZED (
    DELETE FROM staging
    RETURNING *
)

INSERT INTO archive
SELECT *
FROM moved;

이외에도

Nested Schema
$variable 문법
json_set
json_insert
json_replace
json_remove
Recursive CTE의 USING KEY
SQL 표준 FETCH FIRST
UNNEST in GROUP BY

등이 추가되거나 개선된다.

SQL 하나만으로 데이터 처리 파이프라인을 구성할 수 있는 영역이 조금씩 넓어지는 모습이다.

7. S3를 많이 쓴다면 Async I/O가 중요하다

현대 데이터 분석 환경에서는 데이터가 로컬 디스크보다 S3 같은 Object Storage에 존재하는 경우가 많다.

S3
 │
 ├─ parquet
 ├─ parquet
 ├─ parquet
 └─ parquet
      │
      ▼
    DuckDB

DuckDB는 이전에도 S3 데이터를 병렬로 읽을 수 있었다.

하지만 I/O 자체는 동기식 접근이라는 제약이 있었다.

DuckDB 2.0에서는 엔진 전반에 Asynchronous I/O가 도입된다.

이에 따라 I/O 처리와 Query Processing이 독립적으로 확장될 수 있다.

공식 설명에서도 로컬 저장장치보다는 특히 네트워크 스토리지에서 더 큰 효과를 기대할 수 있다고 설명한다.

지원 범위도 Parquet에서 시작해 CSV와 DuckDB 자체 파일 포맷으로 확대되고 있으며, 비동기 Parquet 쓰기도 포함된다.

[Inference] S3 + Parquet 기반 분석 파이프라인을 사용하는 개발자라면 DuckDB 2.0에서 가장 체감하기 쉬운 변화 중 하나가 될 가능성이 높다.

8. 쿼리 엔진도 상당히 빨라졌다

DuckDB 2.0에서는 기존 SQL을 수정하지 않아도 성능 향상을 얻을 수 있도록 Optimizer와 Execution Engine에도 많은 변경이 들어갔다.

대표적으로

Join 아래로 Partial Aggregate Pushdown
중복 Aggregate 재사용
Recursive CTE Engine 재작성
메모리 초과 Aggregate의 Disk Spill
Partition-aware Query Planning
Row Group Pruning 확대

등이다.

공식 블로그의 한 마이크로 벤치마크가 재미있다.

100만 개 Edge를 대상으로 Recursive CTE를 실행한 테스트다.

버전실행시간

DuckDB 1.5.4	4.90초
DuckDB 2.0 Preview	0.12초

약 40배 차이다.

다만 이는 특정 Recursive CTE 마이크로벤치마크 결과이므로 DuckDB 2.0의 모든 쿼리가 40배 빨라진다는 뜻은 아니다.

9. Storage Format도 2.0으로 바뀐다

DuckDB 2.0에서는 기본 Storage Format도 v2.0.0으로 변경된다.

변화는 꽤 내부적이지만 실제 운영에서는 중요하다.

Column Metadata를 Lazy Loading 방식으로 변경하고,

DICT_FSST 문자열 압축을 기본으로 사용하며,

Delete 정보를 더 작게 저장한다.

또 데이터를 읽을 때 Corruption Validation도 강화된다.

DuckDB 팀의 설명에 따르면 특히 큰 Index와 매우 많은 Column을 가진 Table을 열 때 로딩 속도와 메모리 사용량이 개선된다.

10. PostgreSQL Parser와도 작별한다

DuckDB는 오랫동안 PostgreSQL에서 파생된 SQL Parser를 사용했다.

DuckDB 2.0에서는 이것도 바뀐다.

자체 개발한 PEG 기반 SQL Parser가 도입된다.

사용자 입장에서 SQL 문법이 갑자기 달라지는 것은 아니다.

호환성을 유지하는 것이 목표다.

하지만 내부적으로는 꽤 중요한 변화다.

특히 Extension이 SQL Grammar 자체에 개입할 수 있게 된다.

[Inference] 장기적으로는 DuckDB Extension이 단순한 함수 추가 수준을 넘어 새로운 SQL 문법 자체를 제공하는 형태까지 확장될 가능성이 있다.

11. Extension 생태계도 크게 달라진다

DuckDB Extension 개발에는 한 가지 번거로운 문제가 있었다.

DuckDB 버전이 바뀌면 Extension을 다시 빌드해야 하는 경우가 많았다는 것이다.

DuckDB 2.0에서는 C API가 크게 정비된다.

그리고 상당 부분에 Stable ABI를 제공할 계획이다.

구조는 대략 다음과 같다.

My Extension
      │
      ▼
Stable C ABI
      │
      ▼
DuckDB
1.x → 2.x → ...

Extension 개발자가 DuckDB 릴리스마다 Extension을 다시 맞춰 빌드해야 하는 부담을 줄이는 것이 목표다.

Rust 기반 Extension을 위한 binding도 작업 중이다.

또 하나 재미있는 기능이 있다.

기업이나 개발자가 자신의 Extension Repository를 직접 운영할 수 있게 된다.

CREATE EXTENSION REPOSITORY my_repo
FROM 'https://extensions.example.org';

INSTALL my_ext
FROM my_repo;

RSA Public Key를 이용해 Extension을 검증하는 구조도 함께 제공될 예정이다. 해당 기능은 공식 프리뷰 게시 시점에는 일부가 개발 중이라고 명시되어 있다.

기업 내부 DuckDB Extension Store 같은 것도 가능해지는 셈이다.

결국 DuckDB 2.0에서 가장 중요한 변화는 무엇일까

기능 하나만 고르라면 Quack이나 Async I/O일 수도 있다.

하지만 더 중요한 것은 DuckDB의 포지션 변화라고 생각한다.

예전의 DuckDB를 단순화하면 이랬다.

Application
    │
    ▼
 DuckDB
    │
    ▼
Local File

DuckDB 2.0이 그리고 있는 그림은 상당히 다르다.

                ┌─ PostgreSQL
                │
Application ─ DuckDB ─ MySQL
                │
                ├─ S3 / Parquet
                │
                ├─ DuckLake
                │
                └─ Remote DuckDB

여기에

JSON / VARIANT
Vector Similarity
Trigger
Extension
Async I/O

까지 들어간다.

[Inference] 이런 방향이 이어진다면 DuckDB는 단순한 Embedded Analytics Database를 넘어 애플리케이션과 여러 데이터 저장소 사이에 놓이는 경량 분석 엔진이라는 역할을 더 강하게 가져갈 가능성이 있다.

그렇다고 PostgreSQL이나 MySQL을 대체하는 데이터베이스가 된다고 단정하기에는 이르다.

오히려 흥미로운 점은 기존 데이터베이스를 없애려 하기보다 연결하려 한다는 것이다.

PostgreSQL은 그대로 두고,

데이터는 S3에 그대로 두고,

Parquet도 그대로 둔다.

그리고 필요한 순간 DuckDB가 그 위에서 SQL을 실행한다.

AI 개발자에게 DuckDB 2.0이 흥미로운 이유

최근 AI 서비스를 만들다 보면 데이터 구조가 꽤 복잡해진다.

사용자 데이터 → PostgreSQL

로그 → JSON

분석 데이터 → Parquet / S3

Embedding → Vector

AI 결과 → JSON

실험 데이터 → CSV

예전에는 각각 다른 도구를 붙이는 것이 자연스러웠다.

[Inference] DuckDB 2.0의 여러 기능을 조합하면 일부 규모의 시스템에서는 이 데이터들을 하나의 SQL 분석 계층에서 다루는 아키텍처를 고려해볼 수 있다.

특히

S3 + Parquet + PostgreSQL + JSON + Embedding

조합을 사용하는 개발자라면 DuckDB 2.0은 꽤 주목할 만하다.

DuckDB는 더 이상 단순한 '작은 DB'만은 아니다

DuckDB 2.0 프리뷰를 읽으면서 가장 인상적이었던 부분은 기능의 개수가 아니었다.

방향이었다.

DuckDB는 여전히 가볍게 사용할 수 있는 In-process Database라는 장점을 유지하려 한다.

그러면서 동시에

Server

Remote Query

Object Storage

Lakehouse

Semi-structured Data

Vector Search

Extension Ecosystem

영역까지 조금씩 확장하고 있다.

공식 로드맵에도 Quack 안정화, Async I/O, Rust Extension 지원, Iceberg·Delta·Lance·DuckLake 개선 등이 포함되어 있다. 다만 로드맵 항목은 변경될 수 있으며 특정 시점 출시가 보장된 것은 아니다.

DuckDB 2.0의 정식 버전은 2026년 가을 출시가 예정되어 있다. 정확한 세부 기능과 Breaking Changes는 정식 Release Announcement에서 다시 확인할 필요가 있다.

하지만 방향만큼은 꽤 명확해 보인다.

DuckDB는 파일을 분석하는 작은 SQL 엔진에서, 데이터가 있는 곳으로 직접 찾아가는 SQL 엔진으로 확장되고 있다.

휴먼 디자이너를 AI 디자인 에이전트로 복제

행복한 수지아빠 — Fri, 21 Aug 2026 11:16:09 +0900

X의 Karan 님(@kmeanskaran)

System Design for Agent Systems (Part 1)

x.com

디자이너의 머릿속을 복제해 누구나 90점 이상의 UI를 만들게 한다

핵심 아이디어를 한 문장으로 정리하면 다음과 같습니다.

“디자이너가 직접 모든 화면을 만드는 대신, 디자이너의 판단 기준과 작업 프로세스를 코드·문서·디자인 시스템으로 구조화하고 AI가 이를 매번 참조하도록 만든다.”

즉, 단순한 AI UI 생성기가 아니라 ‘디자이너의 사고 과정 자체를 시스템화’한 것입니다.

1. 왜 이런 시스템을 만들었나

기존 NEWT 개발 조직은 대략 다음과 같았습니다.

Before

3개 팀

팀마다
PM 1명
엔지니어 약 3명
디자이너 1명

그런데 AI 도입 이후 개발 속도가 빨라지고 엔지니어의 풀스택화가 진행되면서 소규모 팀을 많이 만들 수 있게 되었습니다.

After

8개 팀

그중
3개 팀 → 디자이너 있음
5개 팀 → 디자이너 없음

문제는 개발팀 수는 늘어나지만 디자이너 수는 그대로라는 것입니다.

디자이너 한 명이 여러 팀을 담당할 수도 있지만,

모든 화면 직접 디자인
↓
모든 화면 검토
↓
수정
↓
다시 검토

를 반복하는 것은 현실적으로 어렵습니다.

그러나 개발 속도를 위해 디자인 품질을 포기할 수도 없습니다.

그래서 이들이 내린 결론은 다음과 같습니다.

UI 품질이 흔들리는 이유는 디자인 판단 기준이 디자이너의 머릿속에만 있기 때문이다.

그렇다면

디자이너 머릿속의 판단 기준을 밖으로 꺼내 AI가 읽을 수 있게 만들자.

라는 접근입니다.

2. 목표

최종 목표는 다음과 같습니다.

PM / 엔지니어
        ↓
Claude Code
        ↓
NEWT 디자인 기준 참조
        ↓
90점 수준 UI 생성
        ↓
디자이너 리뷰
        ↓
확정

즉 디자이너의 역할을

Before

디자인 제작자

에서

After

디자인 기준 설계자
+
최종 리뷰어

로 바꾸는 것입니다.

3. 반드시 구현하고 싶었던 5가지

① Figma가 아니라 Claude Code로 UI를 만들 수 있어야 한다

PM이나 엔지니어가 Figma를 능숙하게 다루는 데에는 진입장벽이 있습니다.

반면 회사에서는 Claude Code를 전사적으로 사용하고 있기 때문에 직군에 관계없이 쉽게 사용할 수 있습니다.

그래서 디자인 작업 인터페이스를

Figma

가 아니라

Claude Code

로 설정했습니다.

4. ② 디자이너의 사고 과정을 그대로 재현

디자이너는 보통 바로 화면부터 그리지 않습니다.

실제 과정은 다음과 같습니다.

문제 이해
↓
PRD 확인
↓
기존 UI 조사
↓
경쟁사 조사
↓
여러 디자인안 작성
↓
비교
↓
추천안 결정
↓
세부 UX 검토
↓
디자인 제안

그런데 일반적인 AI UI 생성은

프롬프트
↓
UI 생성

으로 끝나는 경우가 많습니다.

그래서 NEWT에서는 디자인 결과물만 생성하지 않고 디자인 사고 과정 자체를 AI Workflow로 만들었습니다.

5. ③ 디자인 리뷰하기 쉬운 결과물을 만든다

UI 이미지만 던져주면 디자이너가 리뷰하기 어렵습니다.

예를 들어 이런 질문이 발생합니다.

왜 이 화면을 만들었지?

경쟁사는 어떻게 하고 있지?

사용자가 어떤 행동을 해야 하지?

이 버튼을 누르면 어떻게 되지?

이 상태에서는 어떤 UI가 나오지?

그래서 최종 결과물에는 단순 화면뿐 아니라

문제 정의
경쟁사 조사
설계 근거
디자인 후보
추천안
상세 사양

을 모두 포함합니다.

최종적으로 한 장의 HTML 문서로 만들어집니다.

6. ④ 디자인 단계에서는 구현을 잊되, 바로 구현으로 연결

이 부분이 상당히 중요합니다.

디자인 단계에서

API
DB
서버 상태
데이터 연결

같은 것을 고민하기 시작하면 UI 탐색 범위가 제한됩니다.

그래서 디자인 환경에서는 이런 구현 요소를 제거합니다.

하지만 디자인이 확정된 후 다시 UI를 개발하면 비효율적입니다.

그래서

디자인할 때 사용하는 UI 컴포넌트와 실제 서비스에서 사용하는 UI 컴포넌트를 동일하게 만들었습니다.

7. 핵심 아키텍처

전체 시스템에는 2개의 핵심 저장소가 있습니다.

newt-design-system
        +
newt-spec

역할은 명확하게 나뉩니다.

newt-design-system

"어떻게 디자인해야 하는가"
디자인의 기준 / Single Source of Truth

그리고

newt-spec

"무엇을 만들어야 하는가"
PRD / 기능 명세 / 실제 디자인 작업

입니다.

8. newt-design-system

구조는 다음과 같습니다.

newt-design-system/
│
├── tokens/
│   └── newt.tokens.json
│
├── packages/ui/
│   └── src/components/
│
├── design-mock/
│   ├── components/
│   ├── screens/
│   ├── design/contracts/
│   ├── foundations/
│   └── src/
│
├── docs/
│   └── communication-design/
│
├── plugin/
│
└── storybook/

단순 UI 컴포넌트 라이브러리가 아닙니다.

여기에 NEWT 디자인과 관련된 모든 정보를 모읍니다.

예를 들면

색상
폰트
여백
UI Component
UX 철학
UX Writing
브랜드 디자인
Communication Design
Figma Plugin
Storybook

등입니다.

즉

NEWT 디자인의 Single Source of Truth

입니다.

9. Design Token

예를 들어 컬러나 여백을 각각의 화면에서 AI가 마음대로 결정하지 않습니다.

tokens/newt.tokens.json

에 정의합니다.

개념적으로는

{
  "color": {
    "primary": "...",
    "text": "...",
    "background": "..."
  },
  "spacing": {
    "sm": "...",
    "md": "...",
    "lg": "..."
  }
}

같은 형태가 됩니다.

따라서 AI 역시 임의 값을 생성하는 것이 아니라 기존 토큰을 사용합니다.

10. 실제 제품과 디자인 시안이 같은 UI Component 사용

이 시스템에서 가장 중요한 결정 중 하나입니다.

처음에는 디자인 시안을 일반 HTML로 만들었습니다.

그런데 문제가 발생했습니다.

화면 A Button
17px

화면 B Button
16px

화면 C Button
padding 약간 다름

AI가 계속 비슷하지만 조금씩 다른 컴포넌트를 만들었습니다.

그래서

packages/ui

를 만들고 실제 서비스와 디자인 mock이 모두 동일한 컴포넌트를 사용하도록 변경했습니다.

               packages/ui
                    │
           ┌────────┴────────┐
           │                 │
실제 NEWT 서비스       design-mock

따라서 디자인 시안 단계부터 실제 서비스와 동일한 버튼, 카드, 입력창 등이 사용됩니다.

이것이 상당히 중요한 포인트입니다.

11. design-mock

design-mock은 디자인 실험 공간입니다.

Next.js 앱으로 만들어져 있습니다.

여기서는

API
Backend
DB

를 연결하지 않습니다.

UI/UX만 집중해서 검토합니다.

12. 디자인을 4단계로 구조화

디자인을 대략 다음과 같은 계층으로 나눕니다.

Page
 └─ Section
      └─ Domain Component
            └─ UI Component

예를 들어 여행상품 상세 화면이라면

TourDetailPage

 ├─ HeroSection
 ├─ PriceSection
 │    ├─ PriceCard
 │    │    ├─ Text
 │    │    ├─ Badge
 │    │    └─ Button
 │
 └─ ScheduleSection

처럼 됩니다.

13. 실제 코드와 공유하는 것은 UI Component만

흥미로운 부분입니다.

UI Component

만 실제 제품과 공유합니다.

반면

Domain Component
Section
Page

는 디자인 mock 전용입니다.

왜냐하면 실제 제품에서는 이 부분들이 비즈니스 로직에 따라 다시 구성되기 때문입니다.

대신 이름과 구조는 동일하게 맞춥니다.

그래서 디자인팀과 개발팀이

PriceSection
TourHero
PriceCard

같은 동일한 언어로 이야기할 수 있습니다.

14. Component Contract

AI가 UI 컴포넌트를 정확하게 이해하려면 단순 TSX 코드만으로 부족합니다.

따라서

design/contracts/

안에 컴포넌트의 기계 판독 가능한 사양을 관리합니다.

예를 들어 개념적으로

Button

Variant
- Primary
- Secondary
- Text

Size
- Small
- Medium
- Large

Usage
Primary action은 페이지당 하나를 권장

Avoid
위험 작업에서 Primary 사용 금지

같은 것입니다.

즉 AI용 디자인 명세서입니다.

15. MCP를 이용해 AI가 디자인 시스템을 읽는다

여기서 MCP가 등장합니다.

design-mock은 Next.js 웹앱인 동시에

design-system MCP Server

역할을 합니다.

Claude Code가 이 MCP를 이용해 NEWT 디자인 시스템을 검색합니다.

예를 들어 AI가

여행 상세페이지의 가격 영역을 수정해줘.

라는 요청을 받으면

전체 디자인 시스템을 읽지 않습니다.

대신

get_section("price")

같은 방식으로 필요한 부분만 가져옵니다.

버튼이 필요하면

get_ui_component("Button")

을 호출합니다.

16. 필요한 만큼만 가져오는 것이 중요

NEWT에는 화면이 매우 많기 때문에 전체 디자인 시스템을 매번 LLM Context에 넣는 것은 비효율적입니다.

그래서 검색 단위를 나눕니다.

Page
Section
Domain Component
UI Component
Token
UX Writing

Claude가 필요한 디자인 정보만 가져올 수 있습니다.

즉 일종의

Design RAG

구조라고 볼 수도 있습니다.

17. 회사 공용 MCP

또 중요한 것이

reiwatravel-mcp

입니다.

각 프로젝트마다 MCP를 설치해야 한다면

설정 파일 추가
Server 실행
Token 설정
권한 설정

등이 필요해서 사람들이 잘 사용하지 않게 됩니다.

따라서 사내 공통 MCP 환경을 구축했습니다.

결과적으로 회사 직원은

어떤 Repo
어떤 프로젝트
어떤 직군

에서도 NEWT Design System을 불러올 수 있습니다.

18. 두 번째 저장소 newt-spec

이곳에는

PRD
기능 정의
UX Specification
Design Workflow

가 들어갑니다.

그리고 중요한 AI Skill이 존재합니다.

대표적인 것이

design-builder

입니다.

19. design-builder Skill 구조

design-builder/
│
├── SKILL.md
│
├── references/
│   ├── principles.md
│   ├── proposal-rules.md
│   ├── checklist.md
│   └── ...
│
├── scripts/
│
└── templates/

여기서 가장 중요한 것은

SKILL.md
+
references/

입니다.

20. SKILL.md = 디자이너의 작업 프로세스

SKILL.md에는 Step 0~8까지 디자인 프로세스를 정의합니다.

즉 Claude에게

"디자인해."

라고 요청하는 것이 아니라

Step 0
문제 파악

Step 1
자료 읽기

Step 2
모호한 점 확인

Step 3
조사

Step 4
디자인안 제작

Step 5
비교

Step 6
추천

Step 7
문서화

Step 8
PR 생성

같은 강제 Workflow를 실행시키는 것입니다.

21. references = 디자이너의 머릿속

이 부분이 이 글의 핵심입니다.

references/의 약 11개 파일에 디자인 판단 기준이 들어 있습니다.

예:

principles.md

UI 생성 시 반드시 지켜야 하는
10개의 디자인 원칙

proposal-rules.md

디자인 제안서 작성 규칙

checklist.md

완료 조건

Claude는 체크리스트를 모두 만족하기 전까지 디자인 작업이 완료된 것으로 판단하지 않습니다.

즉

디자이너의 경험
↓
문서화
↓
AI 규칙
↓
매 디자인 작업 적용

구조입니다.

22. 실제 AI 디자인 Workflow

실제 디자인은 대략 다음 순서로 진행됩니다.

Step 1. 전제 확인

어떤 화면인가?
어떤 문제가 있는가?

Step 2. 자료 확인

PRD
Design System
기존 화면
UX Guide

를 읽습니다.

Step 3. 모호한 부분 해결

AI가 질문합니다.

예를 들어

결제 버튼은 항상 노출되어야 하나요?

로그인하지 않은 사용자도 가격을 볼 수 있나요?

설계에 중요한 불확실성을 하나씩 제거합니다.

Step 4. 조사

Claude가

사내 기존 화면
+
경쟁사 화면

을 조사합니다.

그리고

Screenshot
출처
패턴
장단점

을 정리합니다.

Step 5. 여러 디자인안 제작

예:

Option A
기존 패턴 유지형

Option B
정보 계층 개선형

Option C
전환 최적화형

각각 실제 NEWT 컴포넌트를 이용해 작동하는 화면으로 만듭니다.

23. AI가 추천안까지 선택

단순히 3개를 만들고 끝내지 않습니다.

AI가

추천안: B

이유:
- 정보 구조가 명확함
- 기존 NEWT 패턴과 일치
- 구현 변경이 작음
- 모바일에서도 안정적

같은 판단을 내립니다.

24. 최종 결과는 하나의 HTML

최종 결과는 이런 식입니다.

Design Proposal

1. Problem
2. PRD
3. Existing UI
4. Competitor Research
5. Findings

6. Design Option A
7. Design Option B
8. Design Option C

9. Recommended Design

10. Interaction Spec
11. UX Writing
12. Edge Cases

13. Implementation Notes

이 모든 것이 한 페이지 HTML에 들어갑니다.

따라서 디자이너는 화면만 보는 것이 아니라

왜 이런 디자인이 나왔는지

까지 동시에 검토할 수 있습니다.

25. GitHub PR + Vercel Preview

디자인도 코드처럼 PR을 만듭니다.

Claude Code
↓
Design HTML
↓
Git Commit
↓
Pull Request
↓
Vercel Preview
↓
Designer Review

리뷰어는 URL 하나만 클릭합니다.

Vercel Preview에서 실제 화면을 보고 댓글도 남길 수 있습니다.

26. 디자이너 승인

AI 디자인
↓
Designer Review
↓
수정
↓
Approve
↓
구현

방식입니다.

중요한 점은 AI가 디자이너를 없애는 시스템이 아니라는 것입니다.

AI는 90점 정도를 목표로 하고,

마지막 10점

을 디자이너가 판단합니다.

27. 아직 AI에게 맡기기 어려운 것

글에서도 한계를 명확히 인정합니다.

특히

완전히 새로운 UX를 만드는 0→1 디자인

은 아직 어렵다고 이야기합니다.

예를 들어

기존에 전혀 없던 기능
새로운 Interaction
새로운 User Journey
브랜드의 중요한 Experience

등입니다.

이때는

AI → 아이디어 / 참고안
Designer → Figma에서 최종 설계

방식을 사용합니다.

28. 그래서 역할을 구분한다

AI에 잘 맞는 작업

기존 화면 개선
기존 패턴 확장
일상적인 UI 변경
폼 추가
Section 변경
정보 구조 개선

디자이너가 직접 해야 할 가능성이 높은 작업

새로운 서비스
새로운 UX
핵심 Experience
브랜드 핵심 화면
0→1 제품

입니다.

29. Figma의 역할도 바뀐다

기존에는

Figma = 디자인의 Master

였습니다.

하지만 새로운 구조에서는

Design System Code
+
design-mock main

이 Master가 됩니다.

Figma는

필요할 때 쓰는 디자인 도구

로 바뀝니다.

30. 확정 디자인은 main으로 Merge

승인된 디자인은

design-mock/main

에 들어갑니다.

그러면 다음 Claude 작업에서 이 디자인을 다시 참조할 수 있습니다.

즉

AI 디자인
↓
사람 리뷰
↓
승인
↓
Design System 축적
↓
다음 AI 디자인의 Reference

라는 학습 루프가 생깁니다.

31. 이 시스템의 진짜 핵심

기존 Design System은

인간이 읽는 문서

였습니다.

하지만 이 시스템에서는

AI가 매번 읽는 실행 가능한 지식베이스

가 됩니다.

기존 문제는

Design System 작성
↓
사람이 안 봄
↓
오래됨
↓
실제 제품과 달라짐
↓
아무도 안 봄

이라는 악순환이었습니다.

AI가 사용하면 반대가 됩니다.

AI가 매 작업 참조
↓
Design System 중요도 증가
↓
계속 업데이트
↓
더 정확한 AI 결과
↓
사용 증가

32. 앞으로의 목표

현재는 UI Design System이 중심이지만 앞으로는 범위를 확장하려고 합니다.

Product UI
+
UX Writing
+
Brand
+
Communication Design
+
Advertisement
+
Landing Page

까지 모두 하나의 Single Source에 넣는 것입니다.

그리고

reiwatravel-mcp

를 통해 AI에게 전달합니다.

결국 구조는 이렇게 됩니다.

               NEWT Design SSOT
                     │
       ┌─────────────┼─────────────┐
       │             │             │
      UI           Brand       UX Writing
       │             │             │
       └─────────────┼─────────────┘
                     │
                     MCP
                     │
             AI / Claude Code
                     │
       ┌─────────────┼─────────────┐
       │             │             │
      App            LP           Ads

이 글에서 가장 중요한 구조

제가 이 글을 시스템 관점에서 압축하면 다음과 같습니다.

                Designer Brain
                     │
                     ▼
           ┌───────────────────┐
           │ Design Knowledge │
           └───────────────────┘
                     │
       ┌─────────────┼─────────────┐
       │             │             │
    Tokens       Components     Principles
       │             │             │
   UX Writing     Contracts     Checklist
       │             │             │
       └─────────────┼─────────────┘
                     │
                    MCP
                     │
                     ▼
                Claude Code
                     │
                     ▼
                 SKILL.md
                     │
                     ▼
             Design Workflow
                     │
         ┌───────────┼───────────┐
         │           │           │
      Research     Design      Review Doc
         │           │           │
         └───────────┼───────────┘
                     ▼
               Vercel Preview
                     │
                     ▼
               Designer Review
                     │
                     ▼
                   Merge
                     │
                     ▼
              Design SSOT 갱신

특히 주목할 만한 7가지

이 글의 핵심은 Claude Code로 UI를 만든다는 것 자체가 아닙니다.

진짜 중요한 것은 다음 7가지입니다.

디자인 시스템을 AI가 읽을 수 있는 형태로 만든다.
실제 서비스와 디자인 Mock이 동일한 UI 컴포넌트를 사용한다.
Component Contract로 AI에게 사용법까지 알려준다.
MCP로 필요한 디자인 정보만 검색해서 가져온다.
SKILL.md로 디자이너의 작업 순서를 강제한다.
Designer Principles와 Checklist를 파일로 명문화한다.
승인된 결과를 다시 SSOT에 넣어 다음 AI가 사용하게 한다.

일반적인 AI UI 생성과 차이

일반적인 AI UI 제작NEWT 방식

프롬프트 → 화면	PRD → 조사 → 분석 → 여러 안 → 추천
AI가 임의 UI 생성	Design System 기반
임의 CSS	Design Token
비슷한 버튼 새로 생성	실제 Button Component 사용
결과 이미지 중심	작동하는 TSX
맥락 없음	PRD + 조사 + 설계 근거
AI 출력 후 종료	Designer Review
결과가 사라짐	승인 결과 SSOT 편입
Figma가 Master	코드 기반 Design System이 Master

이 시스템을 한 단계 더 추상화하면

사실 이것은 단순한 AI Design System보다 더 큰 개념입니다.

Design System
+
RAG
+
MCP
+
Agent Skill
+
Workflow
+
Code Component
+
Human Review
+
Git
+
CI/CD

를 합친 구조입니다.

저라면 이것을

Design Engineering Agent System

또는

AI-Native Design Operating System

이라고 볼 수 있습니다.

가장 중요한 철학은 이것입니다.

좋은 프롬프트를 만드는 것
        X

좋은 디자인을 반복해서 만들 수 있는
환경을 만드는 것
        O

그리고 글 마지막의 메시지도 사실 여기에 있습니다.

디자이너가 한 화면을 잘 디자인하면 한 화면만 좋아지지만, 디자인 판단 기준 하나를 시스템에 추가하면 모든 팀의 AI 출력이 동시에 좋아진다.

이게 이 방식에서 가장 큰 레버리지입니다.

Reddit Sales System 구축하기

행복한 수지아빠 — Thu, 20 Aug 2026 17:14:41 +0900

아래 내용은 원문을 기준으로 번역·정리한 것입니다.

X의 Chris님(@everestchris6)

how to build a reddit sales system (FULL GUIDE)

x.com

Reddit Sales System 전체 구조

이 글의 핵심은 Reddit에서 직접 자동으로 글을 올리는 봇을 만드는 것이 아니라, Reddit을 계속 읽고 분석해서 “사람이 최종 클릭·게시만 하는 영업 시스템”을 만드는 것입니다.

전체 구조는 2개의 에이전트로 나뉩니다.

Reddit
  ↓
RSS 수집
  ↓
게시글/댓글 DB
  ↓
Subreddit별 사용자 프로필
  ↓
┌──────────────────────┐
│ Agent 1              │
│ 시장/문제/상품 발굴 │
└──────────────────────┘
          +
┌──────────────────────┐
│ Agent 2              │
│ 잠재고객/스레드 발굴│
│ 답변/게시글 작성     │
└──────────────────────┘
          ↓
Dashboard
          ↓
사람이 검토 → 직접 Reddit에 게시

가장 중요한 원칙은 에이전트가 Reddit 계정에 로그인하거나 자동 게시하지 않는 것입니다. 에이전트는 읽기, 분석, 답변 작성, 우선순위 지정까지만 하고 실제 게시 행위는 사람이 자신의 브라우저에서 한다는 방식입니다.

1. 왜 Reddit인가

원문의 주장은 다음과 같습니다.

Reddit에는 거의 모든 문제와 관심사에 대응하는 커뮤니티가 있기 때문에, 사람들이 실제로 사용하는 표현과 실제 불만을 관찰하기 좋은 채널이라는 것입니다.

특히 광고 키워드나 검색량보다 다음과 같은 데이터를 직접 볼 수 있다는 점을 강조합니다.

사람들이 반복해서 질문하는 문제
이미 써본 제품과 실패 이유
돈을 지불할 정도로 절박한 문제
문제를 표현하는 실제 단어
어떤 글이 추천을 받고 어떤 글이 묻히는지
커뮤니티별 문화와 말투

즉, 단순 Reddit 마케팅 시스템이 아니라 시장조사 + Voice of Customer + 콘텐츠 마케팅 시스템에 가깝습니다.

2. Reddit 데이터 수집

원문에서는 별도의 스크레이퍼 대신 Reddit의 공개 RSS를 사용합니다.

예:

https://www.reddit.com/r/startups/.rss

게시글에서는 대략 다음 정보를 가져온다고 설명합니다.

title
author
url
body
timestamp

댓글에서는:

username
comment text
post
permalink
timestamp

을 저장합니다.

그리고 지속적으로 데이터를 저장해 과거 이력을 누적합니다.

30분마다
    ↓
새 Post 수집
새 Comment 수집
    ↓
DB 저장
    ↓
기존 데이터와 중복 제거

원문은 동일 IP에서 요청 속도를 낮게 유지하고 429가 나오면 즉시 반복 요청하지 말라고 제안합니다.

3. Hermes Agent 구축

원문에서는 Nous Research의 Hermes를 중심 에이전트로 사용합니다.

구성은 대략:

Hermes Agent
     ↓
Railway
     ↓
Persistent Storage
     ↓
Telegram Bot

입니다.

Telegram은 알림용입니다.

예:

08:00

오늘 Reddit에서
잠재고객 후보 12건을 발견했습니다.

고우선순위 답변: 4건
게시글 초안: 5건

Dashboard →

에이전트는 파일과 분석 결과를 Persistent Storage에 계속 보존합니다.

4. Subreddit Profile

이 시스템에서 상당히 중요한 부분입니다.

각 subreddit마다 Markdown 파일 하나를 만듭니다.

예:

profiles/
 ├─ smallbusiness.md
 ├─ entrepreneur.md
 ├─ startups.md
 └─ saas.md

파일 내용은 대략 다음과 같습니다.

Demographics

추정 연령, 지역, 직업, 사업 단계 등을 기록합니다.

단, 추정인 경우 명확하게 추정이라고 표시합니다.

Psychographics

무엇을 원하는지, 무엇을 두려워하는지, 어떤 유형의 사람으로 보이기 싫어하는지 등을 분석합니다.

Language

특히 중요한 데이터입니다.

예:

problem phrase:
"getting clients is killing me"

solution phrase:
"outbound that doesn't feel spammy"

failed solution:
"I tried cold email and got nothing"

사람들이 실제로 사용하는 표현을 저장합니다.

Previous attempts

Tried:
- cold email
- LinkedIn outreach
- paid ads

Complaints:
- expensive
- low reply rate
- felt spammy

Content patterns

Upvoted
- 구체적인 경험
- 숫자
- 실패 경험
- 과정 공개

Buried
- 지나친 자기 홍보
- 링크
- AI 느낌의 글

Rules

링크 허용 여부, 자기 홍보 정책, 관리자 규칙 등을 기록합니다.

Tone

post length
sentence style
personal/story driven
formal/informal
header usage

매일 이 파일을 업데이트합니다.

5. Agent 1 — 상품이 없을 때

Agent 1은 무엇을 팔지 찾는 에이전트입니다.

첫 번째 작업은 문제 시장을 찾는 것입니다.

원문 기준 필터는 다음과 같습니다.

긴급한 문제인가?
        ↓
사람들이 이미 돈을 쓰고 있는가?
        ↓
기존 해결책에 불만이 있는가?
        ↓
Reddit에서 접근 가능한가?
        ↓
해결책을 만드는 데 전문 자격이 필요한가?

예를 들어 다음과 같이 분석합니다.

NicheProblemUrgencyExisting spendReddit access

Freelancer	Client acquisition	높음	높음	매우 높음
SaaS founder	User acquisition	높음	높음	높음
Productivity	Focus	중간	중간	매우 높음

의료·법률·안전 등 잘못된 조언으로 피해가 생길 수 있는 분야는 따로 표시하라고 합니다.

6. 반복되는 문제 찾기

일정 기간 데이터를 모은 후 반복되는 질문을 찾습니다.

예:

지난 30일

"How do I get my first 10 customers?"
47회

"Cold email isn't working"
31회

"How much should I charge?"
26회

그리고 각 문제에 대해:

발생 빈도
좌절 강도
현재 사용 중인 해결책
현재 돈을 쓰고 있는지
실제 댓글 예시

등을 분석합니다.

핵심은 AI가 억지로 상품 아이디어를 만들지 않는 것입니다.

좋은 문제가 없으면:

지금 수집한 데이터에는 만들 만한 상품이 없다.

라고 판단하게 합니다.

7. 상품 만들기

반복적인 문제를 발견하면 가이드 형태의 디지털 상품을 만듭니다.

원문 예시는 약:

25~30페이지

입니다.

구성은 다음과 같습니다.

Step 1
무엇을 해야 하는가

Step 2
왜 이것이 작동하는가

Step 3
보통 어디에서 실패하는가

Step 4
기존에 사람들이 시도했던 방법은 왜 실패했는가

중요한 점은 Subreddit Profile의 실제 언어를 사용한다는 것입니다.

8. Landing Page 자동 생성

다음으로 판매 페이지를 만듭니다.

구조:

Headline
↓
고객이 실제 사용한 문제 표현

What's inside
↓
구체적 콘텐츠

Who it's for
↓
대상

Who it's NOT for
↓
비대상

Buy
↓
Checkout

그리고 원문에서는 다음과 같은 조작을 하지 말라고 명시합니다.

가짜 후기 X
가짜 사용자 수 X
가짜 판매량 X
허위 수치 X

9. Agent 2 — 이미 상품이 있을 때

Agent 2는 상품을 판매할 수 있는 Reddit 대화를 찾는 에이전트입니다.

먼저 product.md 같은 파일을 만듭니다.

예:

product.md

내용:

Product
Price

Problem solved

Ideal customer

Not for

Features / contents

Limitations

Customer objections

Honest responses

Real Reddit quotes

이 파일을 모든 답변 작성 전에 참고합니다.

10. 구매 가능성이 높은 Thread 탐색

수집한 Reddit 게시글과 댓글을 분석해서:

“이 사람이 우리 제품이 해결하는 문제를 겪고 있는가?”

를 판단합니다.

단순 키워드 검색이 아니라 의미 기반 매칭을 합니다.

예:

제품 문제가:

cold email reply rate

이어도 사용자는:

"sent 500 emails and got two replies"

라고 말할 수 있습니다.

따라서 Semantic Search 또는 LLM classification을 사용합니다.

점수:

1 = 관련성 거의 없음
2 = 약간 관련
3 = 관련
4 = 강한 관련
5 = 현재 해결책을 찾는 중

특히:

4+

만 답변 후보로 올립니다.

11. 자동 Reply 초안

4점 이상이면 답변을 작성합니다.

여기서 원문의 중요한 철학이 있습니다.

상품을 직접 언급하지 않습니다.

예:

좋지 않은 형태:

제가 만든 SaaS를 한번 써보세요.
https://...

권장 구조:

당신 상황에서는 먼저 X를 확인하는 게 좋습니다.

제가 비슷한 상황에서 봤던 가장 흔한 문제는 Y였습니다.

1. ...
2. ...
3. ...

특히 Z는 피하는 게 좋습니다.

즉:

먼저 도움 → 신뢰 → 자연스러운 관심 → Profile/DM

이라는 Reddit 특유의 구조를 활용합니다.

12. Reply 규칙

원문에서는 다음 규칙을 줍니다.

해당 subreddit 말투 사용

실제 질문에 답하기

Product mention 금지

Link 금지

Thread의 다른 댓글 길이와 비슷하게 작성

마케팅 표현 금지

느낌표 금지

"Great question"으로 시작하지 않기

Dashboard에는:

Reply
Copy button
Open Reddit

가 표시됩니다.

13. 매일 게시글 5개 생성

에이전트는 매일 5개의 글을 만듭니다.

콘텐츠 전략은 흥미롭습니다.

상품의 핵심 방법을 숨기지 말고 그냥 공개하라.

즉:

90% 가치 제공
0% 링크
0% 상품 언급

입니다.

게시글 끝에는:

질문 있으면 답변하겠습니다.

정도의 표현만 사용합니다.

그리고 각 글마다:

이 글이 삭제될 가능성
왜 삭제될 수 있는지
어떻게 수정하면 되는지

도 분석합니다.

14. DM은 자동화하지 않음

Private DM은 RSS에서 읽을 수 없기 때문에 원문 시스템에서는 사람이 직접 처리합니다.

오히려 DM은 매우 중요한 시장조사 데이터라고 설명합니다.

좋은 DM은 다시:

Subreddit Profile
Product Profile

에 반영합니다.

15. Dashboard 1 — Product Discovery

첫 번째 대시보드는 상품 발굴용입니다.

예:

──────────────────────
Reddit Product Radar
──────────────────────

Trending Problems

1. Getting first customers
██████████ 47

"I'm stuck at zero customers"
"cold email isn't working"

2. Pricing
██████ 29

3. Ads too expensive
████ 18

그리고:

Community Changes

r/startups
↑ AI marketing complaints +24%

r/smallbusiness
↑ cold outreach complaints

r/entrepreneur
↓ interest in paid ads

등을 보여줍니다.

16. Dashboard 2 — Sales

두 번째는 실제 영업용입니다.

──────────────────────
Reddit Sales Queue
──────────────────────

URGENT

r/startups
posted 42 min ago

Problem:
"No one replies to my cold emails"

Match score
★★★★★

[Copy Reply]

[Open Reddit]

그 아래에:

READY

Replies 12

Posts 5

Posted today 4

와 같은 큐를 표시합니다.

17. Account Health

계정 상태도 별도 관리합니다.

예:

Account A

Karma       842
Age         14 months
Removals    0
Warnings    0

Removal이 발생하면:

Warning

r/startups
Post removed

Possible reason:
self promotion rule

을 표시합니다.

18. 전체 스케줄

원문 시스템의 운영 주기는 다음과 같습니다.

Every 30 min
Reddit RSS 수집
       ↓
새 게시글/댓글 저장
       ↓
Potential Buyer Matching
       ↓
Reply Draft

밤:

Night

오늘 데이터 분석
↓
Subreddit Profile 업데이트

아침:

Morning

5개 Posts 작성
↓
Reply Queue 정리
↓
Dashboard 업데이트
↓
Telegram 알림

주간:

Weekly

Problem Analysis
↓
새로운 시장 변화
↓
새로운 반복 문제
↓
Product Opportunity

19. 원문에서 추천하는 모델 역할

원문 작성자가 제시한 모델 구성입니다.

역할원문 추천

전체 Orchestration	Claude Opus
Feed 읽기 / Matching	Claude Haiku
글 / 댓글 / Community Profile	Claude Sonnet
대규모 댓글 분석	Gemini Flash
Dashboard / Landing Page 개발	Kimi

다만 이 모델명과 버전은 원문의 주장 그대로이며 현재 실제 제공 모델·가격·성능은 별도 확인이 필요합니다.

시스템 설계 관점에서는 모델명을 고정하기보다는 역할을 다음처럼 분리하는 것이 더 핵심입니다.

Orchestrator LLM
        │
 ┌──────┼────────┐
 ▼      ▼        ▼
Cheap   Writer   Coding
Model   Model    Model
 │       │        │
Feed    Posts    Dashboard
Match   Replies  Landing

20. 이 시스템의 핵심 데이터

이 글에서 가장 가치 있는 부분은 사실 Dashboard도, RSS도 아닙니다.

핵심은 다음 3개의 데이터 자산입니다.

① Reddit Raw Data

posts
comments
threads

        ↓

② Community Intelligence

subreddit profiles

        ↓

③ Customer/Product Intelligence

problems
language
objections
failed solutions
buying intent

데이터가 쌓일수록:

Market Research
      ↓
Product Discovery
      ↓
Content
      ↓
Lead Discovery
      ↓
Sales

가 하나의 파이프라인이 됩니다.

21. 제가 이 시스템을 다시 설계한다면

[Inference] 원문을 그대로 구현하기보다는 Reddit Sales System이라기보다 아래처럼 Reddit Intelligence Platform으로 만드는 편이 확장성이 더 좋습니다.

                Reddit RSS
                    │
                    ▼
             Collector Workers
                    │
                    ▼
              PostgreSQL
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
      Vector DB           Analytics
          │                   │
          ▼                   ▼
 Problem Detection      Trend Detection
          │                   │
          └─────────┬─────────┘
                    ▼
                LLM Layer
                    │
       ┌────────────┼────────────┐
       ▼            ▼            ▼
 Community      Buyer Intent   Content
 Intelligence    Matching      Generator
       │            │            │
       └────────────┼────────────┘
                    ▼
                Dashboard
                    │
             Human Approval
                    │
                    ▼
                  Reddit

그리고 기능을 5개 모듈로 나누는 것이 좋습니다.

Community Radar
커뮤니티 분위기, 문제, 표현, 트렌드 분석
Problem Radar
반복 문제와 사업기회 탐색
Lead Radar
제품과 관련된 구매 의도 게시글 탐색
Content Copilot
답변과 게시글 초안 작성
Sales Queue
사람이 직접 확인하고 Reddit으로 이동해 게시

이렇게 만들면 Reddit뿐 아니라 이후:

Reddit
Hacker News
X
Product Hunt
Indie Hackers
GitHub Issues
Discord
YouTube Comments

같은 데이터 소스를 붙일 수 있습니다.

결국 이 글의 핵심 아이디어를 한 문장으로 요약하면:

AI에게 Reddit 영업을 시키는 것이 아니라, Reddit에서 고객의 문제·언어·구매의도를 계속 수집하고 AI가 “지금 누구에게 무엇을 말해야 하는지” 준비하게 한 뒤 최종 행동은 사람이 하는 시스템입니다.

특히 제품 개발 관점에서는 단순 영업 자동화보다 「시장 문제 발견 → 제품 아이디어 → 제품 생성 → 잠재고객 발견 → 콘텐츠 생성 → 판매 → 다시 고객 데이터 축적」을 하나의 루프로 묶었다는 점이 가장 활용 가치가 높습니다.

GPT-5.6 Luna·Terra·Sol 가격과 성능 비교 — 어떤 모델을 써야 할까?

행복한 수지아빠 — Wed, 19 Aug 2026 09:50:23 +0900

OpenAI의 GPT 모델을 API로 서비스에 적용할 때 가장 고민되는 부분은 결국 두 가지다.

“어떤 모델이 가장 성능이 좋은가?”

그리고

“그 성능에 얼마를 지불해야 하는가?”

현재 OpenAI의 GPT-5.6 계열은 크게 Luna, Terra, Sol 세 가지 모델로 나뉜다.

단순하게 정리하면 다음과 같다.

Luna = 저렴한 대량 처리 모델
Terra = 가격과 성능의 균형 모델
Sol = 최고 수준의 복잡한 추론 모델

특히 세 모델 모두 추론 강도를 조절할 수 있기 때문에 서비스의 성격에 따라 상당히 세밀한 비용 최적화가 가능하다.

이번 글에서는 GPT-5.6 Luna, Terra, Sol의 API 가격, 추론 성능, 벤치마크, 그리고 실제 서비스에서 어떻게 모델을 선택하면 좋은지 정리해본다.

1. GPT-6이 아니라 GPT-5.6이다

먼저 모델명을 정확하게 구분할 필요가 있다.

Luna, Terra, Sol은 현재 GPT-6 모델이 아니라 GPT-5.6 계열이다.

구조는 다음과 같이 이해하면 쉽다.

GPT-5.6
 ├─ Luna
 ├─ Terra
 └─ Sol

세 모델은 같은 GPT-5.6 계열이지만 가격과 추론 성능에서 큰 차이가 있다.

2. GPT-5.6 모델별 API 가격

2026년 8월 19일 기준 가격은 다음과 같다.

모델입력 100만 토큰캐시 입력출력 100만 토큰

GPT-5.6 Luna	$0.20	$0.02	$1.20
GPT-5.6 Terra	$2.00	$0.20	$12.00
GPT-5.6 Sol	$5.00	$0.50	$30.00

가격만 보면 차이가 상당히 크다.

Luna → Terra

입력과 출력 모두 약 10배 비싸진다.

Terra → Sol

약 2.5배 비싸진다.

Luna → Sol

무려 25배 차이가 난다.

즉 단순 API 비용만 생각하면 Luna가 압도적으로 저렴하다.

3. Luna, Terra, Sol의 포지션

모델을 쉽게 구분하면 다음과 같다.

GPT-5.6 Luna

대량 처리 + 비용 최적화 모델

예를 들면 다음과 같은 작업에 적합하다.

문서 요약
번역
정보 분류
간단한 챗봇
데이터 가공
검색 결과 정리
대량 콘텐츠 처리
간단한 AI Agent

API 호출량이 많은 서비스라면 가장 먼저 고려할 수 있는 모델이다.

GPT-5.6 Terra

성능과 비용의 균형형 모델

Luna보다 훨씬 높은 비용이 들지만 복잡한 작업에서 안정적인 성능을 기대할 수 있는 위치다.

예를 들면 다음과 같다.

AI 코딩 에이전트
복잡한 문서 분석
업무 자동화
데이터 분석
리서치
코드 리뷰
디버깅
다단계 Agent Workflow

실제 SaaS나 AI Agent 서비스를 만든다면 가장 범용적인 모델이 될 가능성이 높다.

GPT-5.6 Sol

최고 수준의 복잡한 추론 모델

가장 비싸지만 어려운 문제를 풀어야 할 때 사용하는 모델이다.

대표적인 영역은 다음과 같다.

복잡한 시스템 설계
고난도 프로그래밍
대규모 코드 분석
수학 문제
과학적 추론
장시간 Agent 작업
복잡한 의사결정
멀티스텝 리서치

쉽게 말하면 비용보다 결과 품질이 중요한 작업에 사용하는 모델이다.

4. 추론 강도도 조절할 수 있다

GPT-5.6의 재미있는 점은 모델만 선택하는 것이 아니라 Reasoning Effort, 즉 추론 강도까지 선택할 수 있다는 것이다.

지원되는 단계는 다음과 같다.

none
low
medium
high
xhigh
max

즉 Luna라고 해서 항상 단순한 모델처럼 동작하는 것은 아니다.

예를 들어

Luna + none

으로 사용하면 매우 저렴하고 빠른 작업 처리가 가능하다.

반대로

Luna + high

를 사용하면 Luna에서도 훨씬 깊은 추론을 수행하도록 설정할 수 있다.

5. Reasoning을 높이면 API 단가도 올라갈까?

여기서 중요한 부분이 하나 있다.

Reasoning을

low
→ medium
→ high
→ xhigh
→ max

로 높인다고 해서 토큰 단가 자체가 변경되는 것은 아니다.

하지만 실제 비용은 증가할 수 있다.

그 이유는 모델이 문제를 해결하기 위해 사용하는 Reasoning Token이 증가할 수 있기 때문이다.

즉

토큰 가격
=
동일

이지만

사용 토큰 수
=
증가 가능

하기 때문에 최종 API 비용은 올라갈 수 있다.

6. 모델별 추론 성능 비교

공개된 벤치마크 기준으로 모델 간 성능을 비교하면 다음과 같다.

BenchmarkLunaTerraSol

Artificial Analysis Intelligence Index	51.2	55.0	58.9
Coding Agent Index	74.6	77.4	80.0
Agents' Last Exam	50.3%	50.4%	52.7%
GPQA Diamond	92.3%	92.9%	94.6%
FrontierMath Tier 1–3	78.6%	84.9%	89.0%
FrontierMath Tier 4	58.5%	68.3%	83.0%
BrowseComp	83.3%	87.5%	90.4%
OSWorld 2.0	45.6%	50.2%	62.6%

여기서 상당히 흥미로운 특징이 나타난다.

7. 쉬운 문제에서는 Luna도 상당히 강하다

가격은 Luna와 Sol이 무려 25배 차이가 난다.

하지만 전체 Intelligence Index를 보면

Luna   51.2
Terra  55.0
Sol    58.9

정도다.

가격 차이에 비해 일반적인 벤치마크 차이는 생각보다 크지 않다.

따라서 단순한 작업에서 무조건 Sol을 사용하는 것은 비용 효율이 떨어질 수 있다.

8. 어려운 문제에서는 Sol의 차이가 커진다

반대로 문제 난도가 높아질수록 Sol의 강점이 분명하게 나타난다.

대표적인 사례가 FrontierMath Tier 4다.

Luna   58.5%
Terra  68.3%
Sol    83.0%

Luna와 Sol의 차이가 무려 24.5%p다.

OSWorld 2.0에서도 비슷하다.

Luna   45.6%
Terra  50.2%
Sol    62.6%

즉 일반적인 작업에서는 Luna도 충분히 강하지만, 매우 복잡한 Agent 작업이나 고난도 추론에서는 Sol의 가치가 커지는 구조라고 볼 수 있다.

9. 가격 대비 성능을 계산해보면 Luna가 상당히 강하다

가격과 Intelligence Index를 단순 비교해보자.

Luna

입력

$0.20 / 1M tokens

Intelligence Index

51.2

Terra

입력

$2.00 / 1M tokens

Intelligence Index

55.0

Sol

입력

$5.00 / 1M tokens

Intelligence Index

58.9

Luna → Terra로 넘어가면서 비용은 약 10배 증가하지만 Intelligence Index는 약 7% 정도 올라간다.

Sol까지 올라가면 Luna 대비 가격은 25배지만 Intelligence Index 차이는 약 15% 수준이다.

물론 벤치마크 하나만으로 모델의 실제 성능을 평가할 수는 없다.

하지만 대량 API 서비스에서는 Luna의 가격 경쟁력이 매우 크다는 점은 눈여겨볼 만하다.

10. 그렇다면 실제 서비스에서는 어떤 모델을 써야 할까?

[Inference] 서비스에서 모델을 하나만 사용하는 것보다 작업 난도에 따라 모델을 나누는 구조가 비용 효율적일 수 있다.

예를 들어 다음처럼 구성할 수 있다.

작업모델Reasoning

단순 분류	Luna	none
요약	Luna	low
번역	Luna	low
일반 챗봇	Luna	medium
복잡한 질문	Luna	high
업무 자동화	Terra	medium
AI 코딩	Terra	high
복잡한 디버깅	Terra	high
시스템 설계	Sol	high
고난도 연구	Sol	xhigh
매우 어려운 문제	Sol	max

11. 가장 흥미로운 구조는 AI Model Routing

[Inference] 개인적으로 가장 효율적인 아키텍처는 세 모델을 계층적으로 사용하는 방식이다.

예를 들어 사용자의 모든 요청을 처음부터 Sol에게 보내지 않는다.

먼저 Luna가 처리한다.

사용자 요청
      ↓
    Luna
      ↓
처리 가능?
   ↓       ↓
 YES       NO
 ↓          ↓
응답       Terra
             ↓
          처리 가능?
          ↓       ↓
         YES      NO
          ↓        ↓
         응답      Sol

이런 방식을 Model Routing 또는 Model Escalation 구조라고 볼 수 있다.

12. Luna → Terra → Sol 자동 승격

[Inference] 실제 AI 서비스를 만든다면 다음과 같은 구조도 고려할 수 있다.

Level 1

Luna + low

대부분의 일반 요청 처리

Level 2

Luna + high

조금 더 어려운 문제

Level 3

Terra + high

복잡한 Agent / Coding

Level 4

Sol + high

고난도 문제

Level 5

Sol + max

최종 문제 해결 시도

이렇게 하면 비용을 상당히 세밀하게 제어할 수 있다.

13. AI Coding Agent에도 이 구조를 적용할 수 있다

[Inference] 예를 들어 AI 개발 플랫폼을 만든다고 가정해보자.

단순한 코드 작업은 Luna가 처리한다.

변수명 변경
README 수정
간단한 API 작성
테스트 코드 생성

조금 더 복잡하면 Terra로 승격한다.

버그 분석
리팩터링
DB 설계
API 구조 변경

더 어려운 작업은 Sol에게 보낸다.

전체 시스템 설계
복잡한 성능 문제
Race Condition
Distributed System
대규모 Architecture 변경

이런 식으로 만들면 모든 개발 작업에 비싼 모델을 사용하는 것을 피할 수 있다.

14. 컨텍스트 길이도 상당히 크다

세 모델 모두 최대 약

1.05M tokens

수준의 컨텍스트를 지원하고 최대 출력은

128K tokens

수준이다.

따라서 대규모 코드베이스 분석이나 긴 문서를 처리하는 Agent를 만드는 데도 활용할 수 있다.

다만 매우 긴 컨텍스트를 사용할 경우 별도의 Long Context 가격 정책이 적용될 수 있으므로 대규모 문서를 항상 전체 입력하는 방식보다는 검색·RAG·Context Engineering과 함께 사용하는 것이 비용 측면에서 중요하다.

15. 결론

GPT-5.6 Luna, Terra, Sol을 한 문장으로 정리하면 다음과 같다.

Luna

가격 대비 성능 최강

대량 서비스와 일반적인 AI 기능에 적합하다.

Terra

AI Agent와 코딩의 균형점

성능과 가격을 모두 고려해야 하는 업무형 서비스에 적합하다.

Sol

최고 난도의 문제 해결

비용보다 결과 품질이 중요한 복잡한 작업에 적합하다.

그리고 실제 서비스를 만든다면 가장 흥미로운 전략은 특정 모델 하나를 선택하는 것이 아니다.

[Inference] 오히려

Luna
 ↓
Terra
 ↓
Sol

형태의 다단계 AI Model Router를 만드는 것이 비용과 성능을 동시에 관리하는 데 유리할 수 있다.

대부분의 요청은 저렴한 Luna가 처리하고, Luna가 해결하지 못하는 문제만 Terra로 넘긴다.

그래도 해결이 어렵다면 마지막으로 Sol을 사용한다.

AI 모델의 성능이 계속 높아지는 시대에는 결국

“가장 좋은 모델을 사용하는 것”보다
“어떤 문제에 어떤 모델을 배치하는가”가 더 중요해질 수 있다.

이것이 GPT-5.6 Luna, Terra, Sol을 바라볼 때 가장 중요한 포인트다.

기준일: 2026년 8월 19일

※ API 가격과 모델 정책은 변경될 수 있으므로 실제 개발 및 서비스 적용 전 OpenAI 공식 API 문서에서 최신 가격과 모델 사양을 다시 확인하는 것이 좋다.

현재 한국의 외환·신용·채권·자금흐름·부동산·부채 현황에 대해 확인

행복한 수지아빠 — Fri, 14 Aug 2026 18:16:53 +0900

2026년 8월 14일 18:11 KST 기준으로 다시 확인했습니다. 환율·채권·주식은 오늘 시장 데이터, CDS는 8월 13일 최신치, 부동산은 8월 10일 기준 주간통계, 가계부채는 최신 공식 총액과 7월 대출 흐름을 사용했습니다.

현재 한국 경제 위기 신호등

지표판정현재 확인값핵심 해석

원/달러 환율	주의 ↓ 개선	1,418.3원 8/14 종가	6월 1,561.5원까지 갔던 극단적 원화 약세에서는 크게 회복
️ 한국 CDS	정상	5년물 22.63bp	현재 가장 중요한 긍정 신호. 국가 신용위험 급등은 관찰되지 않음
국고채 금리	위험	10년 4.31%, 30년 4.66%	현재 6개 중 가장 주의해야 할 지표 중 하나
외국인 자금	주의 ↑ 회복	7월 주식 -62.6억 달러, 8/14 하루 +3.04조원 순매수	대규모 이탈 뒤 최근 강하게 복귀 중
부동산	위험	전국 주간 +0.08%, 서울 +0.21%	붕괴 위험이 아니라 과열·부채 연계 위험
가계부채	위험	1분기 1,993.1조원, 7월 대출 +6.2조원	이미 높은 부채에 올해 대출 증가가 다시 빨라짐

종합 판정: 주의 — 다만 빨간불에 가까운 주의

제 판단으로는 현재 한국이 외환위기·국가부도형 위기에 들어간 상태라고 볼 데이터는 아닙니다. 가장 중요한 이유가 CDS입니다. 한국 5년 CDS가 8월 13일 기준 22.63bp입니다. 참고로 2022년 시장 불안기에는 70bp까지 올라간 적이 있었습니다. 현재 국제시장이 한국 정부의 채무불이행 위험을 급격히 가격에 반영하고 있는 상황과는 상당한 차이가 있습니다. (World Government Bonds)

반면 국내의 금리·부동산·가계부채라는 세 축은 분명히 위험 신호가 켜져 있습니다. 그래서 저는 전체를 정상으로 보기는 어렵습니다.

① 환율 — 주의, 하지만 빠르게 개선 중

8월 14일 서울 외환시장 원/달러 종가는 1,418.3원입니다. (재정경제부)

중요한 것은 방향입니다. 원화는 6월 한때 1달러=1,561.5원까지 떨어져 17년 만의 약세 수준을 기록했는데, 7월에는 8% 이상 반등했습니다. 정부의 달러 매도 개입도 있었고 7월 말 1,418원까지 회복했습니다. (Reuters)

따라서 현재 환율은

1,561 → 1,418

로 상당히 정상화됐습니다.

[Inference] 환율만 보면 위기 방향이 아니라 위기에서 멀어지는 방향입니다. 다만 1,400원대 자체가 낮은 환율은 아니며, 한국은행도 최근 원화 수준이 여전히 인플레이션 압력 요인이 될 수 있다고 평가했습니다. (Reuters)

판정: 주의 → 방향으로 개선 중

② ️ CDS — 정상

제가 6개 가운데 가장 중요하게 보는 지표입니다.

한국 5년물 CDS 최신치는 8월 13일 기준 22.63bp입니다. (World Government Bonds)

CDS는 쉽게 말하면

“한국 정부가 빚을 못 갚을 위험에 대해 보험료를 얼마나 내야 하느냐”

를 국제시장이 가격으로 표현한 것입니다.

[Inference] 30년 국채금리가 사상 최고인데 CDS가 20bp 초반이라는 조합은 상당히 중요합니다.

즉 현재 30년 금리 상승을 시장이 주로

한국 국가부도 위험 ↑

으로 보고 있다기보다,

인플레이션 + 장기금리 + 국채 공급 + 장기채 수급 + 기간 프리미엄

문제로 가격에 반영하고 있을 가능성이 더 높습니다.

판정: 정상

③ 국고채 — 위험

여기는 확실히 안 좋습니다.

8월 14일 한국 국고채 10년물은 약 **4.31%**입니다. 1년 전보다 약 1.48%p 높습니다. (Trading Economics)

30년물은 4.66% 수준이고, 8월 12일에는 4.67%까지 올라 30년물이 도입된 2012년 이후 최고 수준을 기록했습니다. (Trading Economics)

그리고 현재 기준금리는 **2.75%**입니다. (한국은행)

즉 대략

기준금리 2.75%
→ 3년 3.80%
→ 5년 4.05%
→ 10년 4.31%
→ 30년 4.66%

형태입니다. 3년·5년물 최신치는 정부 경제지표에서도 확인됩니다. (재정경제부)

[Inference] 이것은 한국의 장기 자금조달 여건이 상당히 빡빡해지고 있다는 경고입니다.

정부뿐 아니라 회사채 → 기업대출 → PF → 주택담보대출 금리에도 간접적으로 영향을 줄 수 있습니다.

판정: 위험

단, 중요한 구분은:

국채금리 위험 ≠ 국가부도 위험

입니다. CDS가 이를 구분해 주고 있습니다.

④ 외국인 자금 — 주의, 최근 급격히 회복

여기는 재미있는 변화가 나타나고 있습니다.

7월에는 외국인이 한국 주식을 62.6억 달러 순매도했습니다. 그것도 3개월 연속 순유출이었습니다. (Reuters)

그런데 최근 방향이 반대로 바뀌었습니다.

8월 14일 하루만 유가증권시장에서 외국인이 3.04조원을 순매수했고, 코스피는 2.42% 상승한 6,977.94로 마감했습니다. (연합뉴스)

즉,

5~7월: 외국인 이탈
→ 8월: 외국인 다시 매수

라는 전환이 나타나고 있습니다.

[Inference] 따라서 현재 상황을 “외국인이 한국을 탈출하고 있다”고 표현하는 것은 최신 데이터와 맞지 않습니다. 그렇다고 몇 거래일의 매수만으로 3개월간의 자금유출 추세가 완전히 끝났다고 확인할 수도 없습니다.

판정: 주의 → 개선 중

⑤ 부동산 — 위험

여기는 폭락 위험이 아니라 과열 위험이라는 점이 핵심입니다.

한국부동산원 8월 둘째 주(8월 10일 기준) 자료를 보면 전국 아파트 가격은 한 주 동안 +0.08%, 서울은 +0.21% 상승했습니다. 서울 상승률은 직전 주 +0.26%보다는 낮아졌습니다. (연합뉴스)

다만 내부적으로 변화가 있습니다.

강남구는 -0.02%, 서초구는 -0.04%로 하락 전환했지만 중랑 +0.46%, 성북 +0.43%, 서대문 +0.41%, 중구·강북 +0.40% 등 중저가 지역은 상당한 상승세를 이어갔습니다. (연합뉴스)

정부도 현재 주택시장을 심각한 과열 문제로 보고 주택공급·금융대책을 발표한 상태입니다. (Reuters)

[Inference] 따라서 현재 부동산의 위험은

“집값이 무너진다”

보다는

“높은 금리에도 집값 상승 → 다시 대출 증가 → 가계부채 증가”

쪽입니다.

판정: 위험

⑥ 가계부채 — 위험

한국은행이 현재 공식적으로 발표한 최신 분기 총액은 2026년 1분기입니다.

가계신용은 1,993.1조원, 전분기보다 14.0조원 증가했습니다. 이 가운데 가계대출이 1,865.8조원입니다. (한국은행)

2분기 공식 가계신용은 아직 발표 전이며 8월 19일 발표 예정입니다. 따라서 지금 2분기 총액을 확정적으로 말할 수는 없습니다. (한국은행)

다만 더 빠르게 나오는 월별 금융권 대출을 보면:

4월 +3.5조
→ 5월 +9.3조
→ 6월 +8.3조
→ 7월 +6.2조원

입니다. 올해 1~7월 누적으로 +35.3조원 늘었습니다. (아시아경제)

최근 두 달 증가 속도가 떨어진 것은 긍정적이지만, 금융당국도 7월 증가액이 과거 평균보다 여전히 높은 수준이라고 보고 있습니다. (다음 뉴스)

판정: 위험

그래서 제가 현재 가장 걱정하는 것은 이 연결입니다

[Inference]

부동산 가격 상승
↓
주담대·가계대출 증가
↓
가계부채 2,000조원 부근
↓
장기 국채금리 4%대 중후반
↓
가계·기업 이자부담 증가
↓
소비·투자 위축

이 시나리오입니다.

즉 지금 한국의 핵심 위험은 “외환위기”보다는 부동산 + 부채 + 고금리의 조합에 더 가깝습니다.

반대로 실제 외환·국가신용 위기로 발전하고 있다면 원화 급락 + CDS 급등 + 외국인 지속 이탈 + 국채금리 급등이 동시에 나타나는지를 봐야 합니다.

현재는:

환율 → 개선
CDS
외국인 → 개선

인데,

국채
부동산
가계부채

입니다.

그래서 “한국이 당장 위험하다”보다는 “대외위기는 아직 아니지만 내부 금융불균형의 압력이 상당히 높다”가 현재 데이터에 더 맞는 표현입니다.

특히 처음 보여주신 30년 국채 4.6%대는 무시할 숫자는 아닙니다. 앞으로는 CDS가 같이 올라가기 시작하는지를 보는 게 핵심입니다. 30년물은 계속 높은데 CDS가 20bp대에 머물면 장기금리 문제에 가깝고, CDS까지 빠르게 튀기 시작하면 상황의 성격이 달라집니다.

이 지표들은 변동이 빨라서 매일 같은 기준으로 점검하면 변화가 훨씬 잘 보입니다.

AI가 코드를 쓰는 시대, 이제 필요한 것은 ‘소프트웨어 공장’이다 (하네스)

행복한 수지아빠 — Fri, 14 Aug 2026 17:59:46 +0900

AI 코딩 도구가 빠르게 발전하면서 소프트웨어를 만드는 속도는 이전과 비교하기 어려울 정도로 빨라졌다.

Cursor, Claude Code, Codex와 같은 도구를 사용하면 개발자는 몇 시간 만에 기능을 구현하고, 화면을 만들고, 테스트 코드까지 작성할 수 있다. 예전에는 며칠 걸리던 작업이 몇 시간 안에 끝나는 경우도 이제 낯설지 않다.

그런데 여기서 새로운 문제가 생긴다.

코드를 만드는 속도는 빨라졌지만, 좋은 소프트웨어를 지속적으로 배포하는 속도까지 같은 비율로 빨라진 것은 아니다.

AI가 만들어내는 코드가 많아질수록 리뷰해야 할 코드도 늘어난다. 품질 편차도 커지고, 어느 순간부터는 사람이 전체 시스템을 제대로 이해하지 못하는 상황까지 발생한다.

결국 AI 개발의 다음 경쟁력은 ‘코드를 얼마나 빨리 생성할 수 있는가’가 아니라,

AI가 만든 결과물을 어떻게 안정적으로 검증하고 지속적으로 제품으로 내보낼 것인가

로 이동하고 있다.

이 지점에서 다시 주목받는 개념이 있다.

바로 소프트웨어 팩토리(Software Factory)다.

소프트웨어 팩토리란 무엇인가

소프트웨어 팩토리를 단순하게 표현하면 다음과 같다.

사람이 개발 공정을 설계하고, 여러 AI 에이전트가 그 공정 안에서 반복적으로 소프트웨어를 생산하는 개발 체계

여기에서 중요한 단어는 ‘AI’보다 오히려 공정(Process)이다.

일반적인 AI 코딩은 개발자가 AI에게 이렇게 요청하는 형태다.

“로그인 기능 만들어줘.”

AI는 코드를 작성하고, 개발자는 결과를 확인한다.

반면 소프트웨어 팩토리에서는 작업이 조금 다르게 흘러간다.

먼저 요구사항이 표준화된 형태로 입력된다.

무엇을 만들어야 하는지, 어디까지 구현해야 하는지, 어떤 조건을 만족해야 하는지, 어떤 테스트를 통과해야 하는지가 정의된다.

그다음 여러 에이전트가 역할을 나눠 작업한다.

어떤 에이전트는 구현하고, 다른 에이전트는 테스트한다. 또 다른 에이전트는 보안이나 코드 품질을 검사할 수도 있다.

그리고 마지막으로 모든 결과물이 동일한 품질 검사를 통과한다.

이 조건을 만족한 변경만 실제 서비스에 반영된다.

구조를 단순화하면 다음과 같다.

요구사항 → 표준화된 Spec → 작업 Queue → AI Agent → 검증 → 리뷰 → 배포 → 사용자 피드백 → 다시 작업 Queue

이러한 루프가 하나가 아니라 여러 개 동시에 돌아가는 것이 소프트웨어 팩토리의 핵심이다.

AI 코딩과 소프트웨어 팩토리는 다르다

많은 조직이 개발자들에게 AI 코딩 도구를 제공하고 있다.

하지만 AI 도구를 많이 사용하는 조직이 반드시 AI 개발을 잘하는 조직은 아니다.

개발자 10명이 각자 AI를 사용하면 코드 생산량은 크게 증가할 수 있다.

문제는 그다음이다.

리뷰해야 할 Pull Request가 급증하고, 테스트해야 할 기능도 늘어난다. 각 개발자가 서로 다른 방식으로 AI를 사용하면서 코드 스타일이나 설계 방식도 달라질 수 있다.

결국 이런 상황이 발생한다.

코드 생산량은 10배 늘었는데 검증 능력은 그대로다.

이 경우 AI는 오히려 새로운 병목을 만들어낸다.

그래서 소프트웨어 팩토리는 단순히 AI에게 일을 많이 시키는 개념이 아니다.

AI가 만든 결과물이 반드시 일정한 공정을 통과하도록 만드는 것이 핵심이다.

공방의 품질과 공장의 품질

소프트웨어 팩토리를 이해하는 데 좋은 비유가 있다.

‘공방’과 ‘공장’의 차이다.

공방에서는 장인의 실력이 제품의 품질을 결정한다.

좋은 개발자가 있으면 좋은 코드가 나온다.

반면 공장에서는 조금 다르다.

제품의 품질이 특정 작업자의 능력에만 의존하지 않는다.

어떤 자재를 사용했는지, 어떤 공정을 통과했는지, 어떤 검사를 통과했는지가 품질의 근거가 된다.

소프트웨어 역시 같은 방향으로 이동할 수 있다.

기존에는 이런 질문이 중요했다.

“이 코드는 누가 만들었나?”

앞으로는 다음 질문이 더 중요해질 수 있다.

“이 코드는 어떤 기준을 만족했고, 어떤 검사를 통과했나?”

사람이 작성했든 AI가 작성했든 같은 품질 기준을 통과하도록 만드는 것이다.

소프트웨어 팩토리의 네 가지 조건

소프트웨어 팩토리를 운영하려면 최소한 네 가지 요소가 필요하다.

1. 입력의 표준화

AI에게 자유로운 자연어만 던지는 방식으로는 안정적인 결과를 얻기 어렵다.

작업 요청 자체가 일정한 구조를 가져야 한다.

예를 들어 단순히

“구글 로그인 만들어줘.”

라고 요청하는 것이 아니라,

기능 목표
구현 범위
기술적 제약
Acceptance Criteria
테스트 요구사항
보안 요구사항

등을 명확하게 정의한다.

AI에게 좋은 코드를 요구하기 전에 좋은 작업 정의를 제공하는 것이 먼저다.

2. 공통 검증

사람이 작성한 코드와 AI가 작성한 코드가 다른 검사를 받아서는 안 된다.

모든 변경은 동일한 품질 기준을 통과해야 한다.

예를 들어 다음과 같은 항목들이다.

Unit Test
Integration Test
E2E Test
Security Scan
Performance Test
Accessibility
디자인 시스템 준수
API 호환성
코드 품질 검사

AI가 만들었다는 이유만으로 더 느슨한 기준을 적용해서는 안 된다.

오히려 코드 생성량이 커질수록 자동 검증의 비중은 더 중요해진다.

3. 결과의 측정

공장은 측정할 수 있어야 한다.

소프트웨어 팩토리 역시 마찬가지다.

예를 들어 다음과 같은 지표를 볼 수 있다.

개발 사이클 타임
PR Merge 시간
테스트 실패율
배포 후 버그 발생률
Rollback 비율
보안 문제 발생률
Agent 성공률
Human Intervention 비율

어떤 AI 모델이 좋은지보다 더 중요한 질문은 이것일 수 있다.

어떤 개발 루프가 가장 안정적으로 좋은 결과를 만들어내는가.

4. 추적 가능성

생성형 AI는 같은 입력을 주더라도 항상 같은 결과를 만들지는 않는다.

따라서 완벽한 재현성보다는 어떻게 만들어졌는지를 추적할 수 있는 구조가 중요하다.

예를 들어 하나의 변경 사항에 다음 정보가 남을 수 있다.

어떤 Task에서 시작됐는지
어떤 Prompt를 사용했는지
어떤 모델을 사용했는지
어떤 Agent가 실행했는지
어떤 코드 버전을 기반으로 했는지
어떤 테스트를 통과했는지
누가 승인했는지

이 기록은 문제가 발생했을 때 매우 중요하다.

AI가 개발에 더 깊게 들어올수록 코드 자체뿐 아니라 생성 과정 역시 개발 자산이 된다.

결국 핵심은 Harness다

최근 AI Agent 개발에서 자주 등장하는 개념이 Harness다.

Harness는 AI Agent가 일하는 환경과 규칙 전체를 의미한다.

쉽게 말하면 AI에게 제공하는 ‘작업장’이다.

여기에는 다음과 같은 요소가 포함될 수 있다.

Context
Rules
Tools
Permissions
Memory
Runtime
Tests
Quality Gate
Definition of Done

AI 모델이 아무리 좋아도 이런 구조가 없다면 결과 품질은 흔들릴 수밖에 없다.

반대로 모델이 조금 부족하더라도 좋은 Harness가 있다면 일정 수준 이상의 결과를 반복적으로 만들어낼 가능성이 높아진다.

그래서 앞으로 AI 개발에서 중요한 경쟁력은 모델을 선택하는 능력보다 Agent가 안정적으로 일할 수 있는 작업 환경을 설계하는 능력이 될 수 있다.

거대한 AI 하나보다 작은 루프 여러 개

AI Agent를 활용하는 방식에서도 변화가 나타나고 있다.

처음에는 하나의 강력한 Agent에게 긴 작업을 맡기는 방식이 주목받았다.

“이 서비스를 처음부터 끝까지 만들어줘.”

하지만 작업이 길어질수록 Context가 복잡해지고 오류가 누적될 수 있다.

그래서 최근에는 작업을 작게 나누고 짧은 Agent 실행을 반복하는 방식도 많이 논의된다.

예를 들어,

Task 1을 실행한다.

결과를 Git이나 파일에 저장한다.

다음 Task에서는 새로운 Context로 Agent를 실행한다.

그리고 다시 결과를 저장한다.

이런 작은 루프가 반복된다.

결국 소프트웨어 팩토리는 하나의 거대한 AI 개발자가 아니라,

수많은 작은 AI 작업 루프가 연결된 개발 조직

에 가깝다.

디자인 역시 공장의 품질 기준이 된다

소프트웨어 팩토리가 생산하는 것은 코드가 아니다.

사용자가 실제로 사용하는 제품이다.

따라서 디자인 역시 검증 대상이 된다.

예를 들어 다음과 같은 규칙을 자동으로 검사할 수 있다.

지정된 Color Token을 사용했는가
Spacing 규칙을 지켰는가
Typography가 Design System과 일치하는가
Loading 상태가 존재하는가
Empty State가 정의되어 있는가
Error State가 존재하는가
Keyboard Navigation이 가능한가
문구 Tone & Manner가 규칙을 따르는가

이렇게 되면 디자인 시스템은 단순한 Figma 파일이 아니다.

AI와 사람이 모두 읽을 수 있는 제품 품질 규칙이 된다.

디자인도 개발 이전 단계의 작업물이 아니라 배포를 결정하는 Quality Gate의 일부가 된다.

가장 위험한 문제, ‘이해 부채’

AI 개발이 빠르게 확산되면서 새로운 형태의 기술 부채도 등장한다.

바로 이해 부채(Understanding Debt)다.

AI가 코드를 작성하는 속도가 사람이 코드를 이해하는 속도보다 빨라지면 이런 상황이 발생한다.

코드는 계속 증가한다.

테스트도 통과한다.

서비스도 정상적으로 돌아간다.

그런데 어느 순간 문제가 발생했을 때 아무도 해당 코드가 왜 그렇게 만들어졌는지 설명하지 못한다.

전체 코드량과 사람이 실제로 이해하고 있는 코드 사이의 간격이 계속 커지는 것이다.

AI가 많은 코드를 만들어낼수록 이 문제는 더 빠르게 커질 수 있다.

따라서 모든 개발을 무조건 자동화하는 것이 좋은 전략이라고 보기는 어렵다.

같은 AI가 코드와 테스트를 만들 때 생기는 문제

AI 개발에서 특히 조심해야 할 부분이 있다.

같은 Agent가 기능을 구현하고 그 기능의 테스트까지 작성하는 경우다.

AI가 요구사항을 잘못 이해했다고 가정해보자.

그러면 잘못 이해한 요구사항을 기준으로 코드를 작성한다.

그리고 같은 이해를 바탕으로 테스트도 작성한다.

결과적으로 이런 상황이 가능하다.

코드는 잘못됐지만 테스트는 통과한다.

초록색 체크가 반드시 올바른 소프트웨어를 의미하지 않는 이유다.

따라서 중요한 기능에서는 구현과 검증을 분리하거나, 원래 Specification을 기준으로 독립적인 검증을 수행하는 구조가 필요하다.

모든 것을 자동화할 필요는 없다

소프트웨어 팩토리에서 중요한 것은 ‘사람을 없애는 것’이 아니다.

어떤 작업에 사람이 필요한지 결정하는 것이다.

자동화하기 쉬운 작업이 있다.

예를 들어 영향 범위가 작고 실패 여부를 기계적으로 판단할 수 있는 변경이다.

반면 사람이 반드시 판단해야 할 작업도 있다.

인증
결제
개인정보
권한
데이터베이스 Migration
Public API
핵심 Architecture
중요한 보안 변경

이런 영역은 잘못됐을 때 영향이 크다.

따라서 AI가 구현하더라도 사람이 최종 판단을 하는 것이 합리적이다.

목표는 ‘Human 0%’가 아니다.

기계가 검증할 수 있는 것은 자동화하고, 판단이 필요한 곳에는 인간을 남기는 것.

이 경계를 설계하는 것이 중요하다.

AI 시대의 진짜 병목은 코드 생성이 아니다

AI 모델과 컴퓨팅 자원을 늘리면 코드 생성량은 계속 늘릴 수 있다.

하지만 사람의 Attention은 무한하지 않다.

QA 인력도 무한하지 않고, Security Review나 Architecture Review에 사용할 수 있는 시간 역시 제한되어 있다.

결국 AI 개발에서 가장 희소한 자원은 코드가 아니라 검증 능력이 된다.

그래서 앞으로 개발 조직이 고민해야 할 질문도 바뀔 가능성이 높다.

“어떤 AI가 코드를 가장 잘 쓰는가?”

보다

“우리는 AI가 만든 결과를 얼마나 빠르고 정확하게 검증할 수 있는가?”

가 더 중요한 질문이 된다.

개발자의 역할도 달라질 수 있다

AI가 코드를 더 많이 작성하게 된다고 해서 개발자가 필요 없어지는 것은 아니다.

다만 역할의 중심이 이동할 수 있다.

과거 개발자의 핵심 업무가 직접 코드를 작성하는 것이었다면 앞으로는 다음과 같은 일이 더 중요해질 수 있다.

무엇을 만들어야 하는지 정의한다.

Acceptance Criteria를 만든다.

Agent가 사용할 Context와 Tool을 설계한다.

자동화할 수 있는 검증 기준을 만든다.

중요한 Architecture를 결정한다.

그리고 최종 품질을 책임진다.

즉 개발자의 역할이

Coder

에서

Software Factory Designer

로 확장되는 것이다.

AI를 잘 쓰는 회사보다 ‘AI가 일하는 시스템’을 잘 만드는 회사

AI 코딩 도구는 빠르게 평준화될 가능성이 있다.

좋은 모델은 누구나 사용할 수 있고, 좋은 코딩 Agent 역시 많은 조직이 사용할 수 있다.

그렇다면 차이는 어디에서 만들어질까.

결국 조직 내부에 쌓인 다음과 같은 것들이 경쟁력이 될 수 있다.

좋은 Specification을 만드는 방법
좋은 Prompt와 Context
개발 규칙
Design System
테스트 체계
Quality Gate
Security Policy
Agent Workflow
실패 사례와 Feedback Loop

이것들은 단순히 AI 모델을 바꾸는 것으로 얻을 수 없다.

조직이 시행착오를 반복하면서 만들어야 한다.

그리고 이런 구조가 갖춰진 조직에서는 AI Agent가 하나 늘어날 때 단순히 개발자 한 명이 늘어나는 것이 아니라 생산라인 하나가 추가되는 효과가 나타날 수도 있다.

앞으로 중요한 질문

AI 개발의 초반 경쟁은 ‘누가 AI로 더 빨리 코드를 쓰는가’였다.

하지만 그 단계는 빠르게 지나가고 있다.

이제 더 중요한 질문은 이것이다.

AI가 하루에 수백 개의 변경을 만들어낸다면 우리는 그 결과를 어떻게 믿을 것인가?

소프트웨어 팩토리는 그 질문에 대한 하나의 답이다.

AI에게 더 많은 코드를 작성시키는 것이 아니라,

좋은 코드만 살아남는 개발 공정을 만드는 것.

AI 시대의 소프트웨어 경쟁력은 결국 코드 생성량이 아니라,

얼마나 안정적으로 검증하고, 얼마나 반복적으로 좋은 제품을 출하할 수 있는 시스템을 가지고 있는가

에서 결정될 가능성이 크다.

어쩌면 앞으로 가장 중요한 개발 능력은 코드를 잘 작성하는 능력만이 아닐지도 모른다.

AI가 좋은 소프트웨어를 계속 만들어낼 수 있도록 ‘공장’을 설계하는 능력.

그것이 소프트웨어 팩토리가 다시 주목받는 이유다.

Appwrite 뜯어보기: 오픈소스 BaaS는 내부에서 어떻게 동작할까?

행복한 수지아빠 — Wed, 12 Aug 2026 12:25:00 +0900

웹이나 모바일 앱 하나를 만들 때 실제로 필요한 백엔드 기능은 생각보다 많다.

회원가입과 로그인, 데이터베이스, 파일 업로드, 권한 관리, 서버 함수, 실시간 통신, 이메일과 푸시 알림, 웹훅, 배포 환경까지 준비해야 한다.

개별 서비스를 조합해 직접 만들 수도 있지만, Appwrite는 이 영역을 하나의 개발 플랫폼으로 묶으려는 오픈소스 프로젝트다.

Appwrite는 공식 README에서 자신을 웹·모바일·AI 애플리케이션을 위한 오픈소스 개발 플랫폼으로 설명한다. Auth, Databases, Storage, Functions, Messaging, Sites, Realtime 등을 하나의 플랫폼에서 제공하며, Appwrite Cloud를 이용하거나 직접 서버에 Self-hosting할 수 있다.

하지만 Appwrite에서 더 흥미로운 부분은 기능 목록이 아니다.

이 많은 기능을 하나의 백엔드 플랫폼 안에서 어떻게 구조화했는가?

소스 코드를 살펴보면 Appwrite는 꽤 흥미로운 답을 보여준다.

1. Appwrite는 단순한 API 서버가 아니다

Appwrite를 가장 단순하게 보면 다음과 같은 구조다.

Web / Mobile / Server Application
                │
                ▼
             Appwrite
                │
        ┌───────┼────────┐
        │       │        │
       Auth  Database  Storage
        │       │        │
        ├──── Functions ─┤
        │                │
     Realtime         Messaging
        │                │
        └───── Sites ────┘

개발자는 이런 기능을 REST API나 SDK를 통해 사용할 수 있다.

공식 README 기준 주요 제품은 다음과 같다.

Auth — 로그인, 세션, OAuth, MFA, 사용자 인증
Databases — 데이터 저장, Query, Index, Relationship
Storage — 파일 업로드·다운로드와 이미지 처리
Functions — 이벤트 또는 스케줄 기반 서버 코드 실행
Messaging — Email, SMS, Push
Sites — 웹 애플리케이션 호스팅
Realtime — 실시간 데이터 전달

Appwrite는 REST뿐 아니라 WebSocket과 GraphQL도 지원한다고 아키텍처 문서에서 설명한다.

즉 Appwrite를 단순히

"Firebase를 오픈소스로 다시 만든 프로젝트"

정도로 이해하면 내부 구조에서 배울 수 있는 많은 부분을 놓치게 된다.

Appwrite는 오히려 여러 백엔드 기능을 하나의 플랫폼으로 구성하는 방법을 보여주는 대규모 백엔드 시스템 사례로 보는 편이 더 흥미롭다.

2. 핵심은 '모놀리스 + 마이크로서비스' 혼합 구조

Appwrite의 아키텍처에서 가장 먼저 눈에 들어오는 부분이다.

공식 CONTRIBUTING 문서에는 현재 Appwrite 구조가 Monolithic Architecture와 Microservice Architecture의 조합이라고 명시되어 있다.

핵심 API는 하나의 애플리케이션으로 구성한다.

              ┌─────────────────────┐
Client ─────▶ │    Appwrite API     │
              │                     │
              │ Auth                │
              │ Database            │
              │ Storage             │
              │ Functions           │
              │ Teams               │
              │ Users               │
              │ Sites               │
              └─────────────────────┘

반면 시간이 많이 걸리거나 독립적으로 처리할 수 있는 작업은 Worker로 분리한다.

실제 Docker Compose에는 다음과 같은 Worker들이 별도 컨테이너로 존재한다.

appwrite-worker-webhooks
appwrite-worker-deletes
appwrite-worker-databases
appwrite-worker-builds
appwrite-worker-jobs
appwrite-worker-screenshots
appwrite-worker-certificates
appwrite-worker-functions
appwrite-worker-mails
appwrite-worker-notifications
appwrite-worker-messaging
appwrite-worker-migrations

그래서 전체 구조를 단순화하면 다음에 가깝다.

                         ┌──────────────┐
Internet ───────────────▶│   Traefik    │
                         └──────┬───────┘
                                │
                    ┌───────────┴──────────┐
                    ▼                      ▼
             Appwrite API           Appwrite Realtime
                    │
                    ▼
             Application Logic
                    │
          ┌─────────┼─────────┐
          ▼         ▼         ▼
      Database    Redis      Storage
                    │
                    ▼
                 Queue
                    │
       ┌────────────┼──────────────┐
       ▼            ▼              ▼
   Functions     Webhooks       Messaging
     Worker        Worker          Worker
       │
       ▼
 OpenRuntimes
 Executor

README도 API Layer에서는 캐시를 활용하고, 무거운 작업은 Background Worker로 넘긴다고 설명한다.

여기서 Appwrite의 설계 방향을 명확하게 볼 수 있다.

모든 기능을 처음부터 마이크로서비스로 분리하지 않았다.

CONTRIBUTING 문서에 따르면 핵심 API를 모놀리스로 유지한 이유 중 하나는 작은 팀이 더 빠르게 개발하기 위해서였다. 대신 Worker와 내부 서비스는 별도 컨테이너로 나누어 독립적으로 확장할 수 있도록 구성했다.

3. PHP인데 일반적인 PHP 서버와 조금 다르다

Appwrite 서버의 중심 언어는 PHP다.

하지만 일반적인

Nginx
  ↓
PHP-FPM
  ↓
Laravel

형태와는 다르다.

현재 main의 composer.json은 PHP >= 8.5.0과 Swoole 6 확장을 요구하고 있다. 또한 상당수의 핵심 구성요소가 utopia-php 패키지로 나뉘어 있다.

주요 의존성을 보면 다음과 같다.

PHP >= 8.5
Swoole 6
Utopia Platform
Utopia Database
Utopia Queue
Utopia Cache
Utopia Storage
Utopia Messaging
Utopia WebSocket
GraphQL PHP
Redis Extension

Appwrite 내부 개발 가이드 역시 Swoole 기반 비동기 런타임과 Utopia PHP Framework를 핵심 Stack으로 설명한다.

Docker 컨테이너의 기본 실행 명령도 흥미롭다.

CMD [ "php", "app/http.php" ]

별도 PHP-FPM이 아니라 Appwrite 애플리케이션 자체가 HTTP 서버 프로세스로 동작하는 구조다.

4. 거대한 Controller 대신 'Module + Action'

대규모 백엔드에서는 기능이 증가하면서 Controller가 비대해지는 문제가 자주 발생한다.

Appwrite 역시 과거에는

app/controllers/api/[service].php

형태의 큰 Controller 파일을 사용했지만, 유지보수 문제가 생기면서 신규 개발을 HTTP Module 구조로 이전하고 있다고 설명한다.

현재 구조는 다음과 같다.

src/Appwrite/Platform/Modules/

그 아래에 기능별 Module이 존재한다.

Account
Avatars
Databases
Functions
Health
Notifications
Projects
Sites
Storage
Teams
Tokens
Users
VCS
Webhooks
...

실제 Appwrite Platform 클래스가 이 모듈들을 하나씩 등록한다.

각 Module 내부는 대략 다음 패턴을 따른다.

Modules/
  Teams/
    Module.php

    Services/
      Http.php
      Workers.php
      Tasks.php

    Http/
      Teams/
        Create.php
        Get.php
        Update.php
        Delete.php
        XList.php

내부 개발 가이드에서는 HTTP Endpoint의 경로까지 파일 구조에 반영하도록 규칙을 정의하고 있다.

예를 들어

POST /v1/teams

API는

Modules/Teams/Http/Teams/Create.php

에서 구현된다.

실제 코드를 보면 하나의 Action에서 HTTP Method, Path, Scope, Event, Audit, SDK Metadata, Parameter, Dependency Injection까지 정의한다.

개념적으로 단순화하면 다음과 같다.

class Create extends Action
{
    public function __construct()
    {
        $this
            ->setHttpMethod('POST')
            ->setHttpPath('/v1/teams')
            ->label('event', 'teams.[teamId].create')
            ->label('scope', 'teams.write')
            ->inject('dbForProject')
            ->inject('queueForEvents')
            ->callback($this->action(...));
    }
}

여기서 눈여겨볼 점은 하나의 Endpoint 정의가 단순 Controller 함수가 아니라는 것이다.

HTTP Route
+
Validation
+
Authorization Scope
+
Audit
+
Event
+
SDK Metadata
+
Dependency Injection

이 모두가 하나의 Action Contract에 들어간다.

API 구현과 SDK 생성 규칙을 최대한 동일한 구조에서 관리하려는 방식이다.

5. 무거운 작업은 Queue 뒤로 넘긴다

Appwrite 내부에서 중요한 구성요소 중 하나가 Event Queue다.

실제 Event.php에는 다양한 Queue 이름이 정의되어 있다.

v1-database
v1-deletes
v1-audits
v1-mails
v1-notifications
v1-functions
v1-webhooks
v1-certificates
v1-builds
v1-jobs
v1-screenshots
v1-messaging
v1-executions
v1-migrations

Event가 발생하면 Publisher를 이용해 Queue에 Payload를 넣는다.

return $this->publisher->enqueue(
    $queue,
    $payload
);

실제 Event 구현에서도 Queue 생성 → Payload 구성 → Publisher enqueue 과정이 확인된다.

이를 구조적으로 보면 다음과 같다.

API Request
    │
    ▼
Business Logic
    │
    ├────────────▶ Database
    │
    ▼
Generate Event
    │
    ▼
Queue
    │
    ├────▶ Webhook Worker
    ├────▶ Function Worker
    ├────▶ Messaging Worker
    ├────▶ Build Worker
    └────▶ Delete Worker

실제로 Team 생성 API에서도 데이터베이스 작업 후 queueForEvents에 이벤트 관련 Parameter를 설정한다.

이 패턴은 대규모 백엔드에서 매우 자주 등장한다.

사용자가 기다릴 필요가 없는 작업을 동기 HTTP Request에서 분리하면 API와 Background Processing을 별도로 운영할 수 있기 때문이다.

6. Redis는 단순 캐시 이상으로 중요하다

Appwrite Compose에는 Redis가 별도 서비스로 포함되어 있다.

현재 설정에서는 Redis 7.4 Alpine 이미지를 사용하며 최대 메모리와 LRU 정책도 설정되어 있다.

Appwrite 개발 가이드에서는 Redis의 역할을 다음처럼 정리한다.

Cache
Queue
Pub/Sub

그래서 전체 Appwrite 구조를 이해하려면 Redis를 단순한 캐시 서버라고 생각하기보다는

서비스와 Worker 사이를 연결하는 인메모리 인프라

라는 관점에서 보는 것이 더 적절하다.

7. 데이터베이스도 하나만 사용하는 구조가 아니다

2026년 8월 현재 main의 개발 환경 설정은 특히 흥미롭다.

.env에는 기본 Platform Database와 DocumentsDB, VectorsDB가 서로 다른 Adapter를 사용할 수 있도록 구성되어 있다.

현재 기본 설정은 다음과 같다.

Main DB
PostgreSQL

DocumentsDB
MongoDB

VectorsDB
PostgreSQL

그리고 Redis는 별도로 사용한다.

Docker Compose에도 MariaDB, MongoDB, PostgreSQL이 각각 정의되어 있다.

특히 현재 main에는

DocumentsDB
TablesDB
VectorsDB
Embeddings

처럼 데이터베이스 기능이 세분화되고 있다. VectorsDB에는 Collection과 Transaction을 포함한 별도 HTTP API 구조도 존재한다.

Compose에는 별도의 Embedding 서비스도 포함되어 있다.

appwrite-embedding:
  image: appwrite/embedding:0.1.0

기본 Embedding Model 설정에는 nomic-embed-text가 지정되어 있다.

즉 현재 개발 브랜치에서는 기존 BaaS 기능뿐 아니라 Vector Database와 Embedding을 위한 AI 애플리케이션 인프라까지 코드베이스에 포함되고 있는 것을 확인할 수 있다.

단, main 브랜치의 기능은 최신 정식 릴리스와 반드시 동일하다고 볼 수 없으므로 버전별 기능 확인은 별도로 필요하다.

8. Serverless Function은 OpenRuntimes가 담당한다

Appwrite Functions도 Appwrite API 프로세스 안에서 직접 실행하지 않는다.

Docker Compose에는 별도의

openruntimes-executor

서비스가 존재한다.

현재 main에서는 openruntimes/executor:0.25.4 이미지를 사용하며 Functions와 Sites의 Runtime을 실행할 수 있도록 구성되어 있다.

또한 Build·Job 처리를 위한

orchestrator-jobs

서비스도 존재한다.

전체 구조를 단순화하면 다음과 같다.

Developer
    │
    ▼
Upload Function
    │
    ▼
Appwrite API
    │
    ▼
Build Worker
    │
    ▼
Jobs / Build Infrastructure
    │
    ▼
OpenRuntimes Executor
    │
    ▼
Isolated Runtime
    │
    ├─ Node
    ├─ PHP
    ├─ Python
    └─ ...

README에서는 현재 Functions 제품이 여러 Runtime을 지원한다고 안내하고 있다.

Appwrite가 단순 API 서버를 넘어 플랫폼으로 복잡해지는 이유 중 하나가 바로 이 Compute Layer다.

9. Realtime도 API 서버와 분리되어 있다

Realtime 역시 별도의 컨테이너다.

appwrite-realtime:
  entrypoint: realtime

Traefik은

/v1/realtime

요청을 Appwrite Realtime 서비스로 라우팅한다.

따라서 HTTP API와 WebSocket 연결을 같은 프로세스에 모두 몰아넣는 구조가 아니다.

               Traefik
                  │
         ┌────────┴─────────┐
         │                  │
     REST / GraphQL      WebSocket
         │                  │
   Appwrite API      Appwrite Realtime

Realtime 연결과 일반 API 요청의 부하 특성이 다르다는 점을 고려한 서비스 분리가 소스 구조에서도 확인된다.

10. 앞단에는 Traefik이 있다

Self-hosted Compose 환경에서 외부 트래픽의 진입점은 Traefik이다.

현재 Compose에서는 Traefik 3.6이 사용되고 있으며 HTTP 80과 HTTPS 443 Entry Point를 구성한다.

Traefik이 요청을 구분해

API
Console
Realtime

등으로 라우팅한다.

전체 구조를 한 번 더 정리하면 다음과 같다.

                    Internet
                       │
                       ▼
                   Traefik
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
      Appwrite      Realtime      Console
        API
          │
          ▼
       Modules
          │
     ┌────┴────┐
     ▼         ▼
 Database     Redis
               │
               ▼
             Queue
               │
      ┌────────┼─────────┐
      ▼        ▼         ▼
 Functions  Webhooks  Messaging
 Worker      Worker     Worker
      │
      ▼
 OpenRuntimes

Appwrite를 이해하는 데 가장 중요한 그림도 사실 이것이다.

11. Self-hosting이 가능한 이유

Appwrite는 Docker 기반 배포를 핵심 설치 방식으로 제공한다.

README에서는 Docker Compose뿐 아니라 Kubernetes, Docker Swarm, Rancher 같은 Container Orchestration 환경에서도 운영할 수 있다고 안내한다.

Dockerfile에는 Storage 관련 디렉터리도 명시적으로 구성되어 있다.

/storage/uploads
/storage/imports
/storage/cache
/storage/config
/storage/certificates
/storage/functions
/storage/debug

Compose에서는 추가로 Functions, Sites, Builds 등을 Volume으로 관리한다.

따라서 Self-hosted Appwrite를 운영한다면 Appwrite API 컨테이너 하나만 관리한다고 생각하기보다는

Reverse Proxy
Database
Redis
Realtime
Workers
Executor
Build infrastructure
Persistent Storage
Certificate

를 포함한 하나의 백엔드 플랫폼 Stack을 운영한다고 이해하는 편이 정확하다.

12. 오픈소스 라이선스는 BSD 3-Clause

Appwrite Server Repository는 BSD 3-Clause License를 사용한다.

라이선스 전문에는 소스 및 바이너리 형태의 재배포와 수정 사용을 허용하면서 Copyright Notice와 Disclaimer 유지 등의 조건을 명시하고 있다.

기업에서 직접 Self-hosting하거나 소스를 분석하려는 경우에도 비교적 접근하기 쉬운 오픈소스 라이선스다.

실제 상용 제품에 수정·재배포하려는 경우에는 Appwrite Server뿐 아니라 함께 사용하는 별도 이미지와 외부 프로젝트들의 라이선스도 각각 확인할 필요가 있다.

13. Appwrite 코드에서 배울 수 있는 다섯 가지

Appwrite를 직접 사용할 계획이 없더라도 백엔드 개발자 입장에서 참고할 만한 설계 요소가 많다.

① 처음부터 모든 것을 Microservice로 만들 필요는 없다

Appwrite는 핵심 API를 Monolith로 유지하면서 Worker를 독립 서비스로 분리한다.

이는

Core Business Logic
        │
        ▼
     Monolith

Heavy / Async Job
        │
        ▼
   Independent Worker

라는 현실적인 분리 방법을 보여준다.

② Side Effect는 Queue 뒤로 분리할 수 있다

메일, Function 실행, Webhook, Messaging, Delete 같은 작업은 별도 Queue와 Worker로 구성되어 있다.

API 서버와 Background Processing의 책임을 분리하는 실제 대규모 사례로 살펴볼 만하다.

③ 기능 단위 Module 구조가 중요하다

Appwrite는 Account, Databases, Functions, Storage, Sites, Teams처럼 도메인별 Module을 구성한다.

프로젝트가 커질수록 단순한

controllers/
services/
repositories/

구조보다

Modules/
  Teams/
  Storage/
  Functions/
  Databases/

처럼 기능 자체를 상위 경계로 두는 방식이 코드 탐색에 유리한 경우가 있다.

④ API 규칙을 코드 구조까지 연결한다

Appwrite의 신규 HTTP Action 파일은 기본적으로

Create
Get
Update
Delete
XList

형태로 제한하는 규칙을 사용한다.

URL, Directory, Action Class, SDK Operation이 최대한 동일한 Resource Model을 표현하도록 만드는 것이다.

대규모 API를 오랫동안 유지할 때 Naming Convention과 Directory Convention 자체가 Architecture의 일부가 될 수 있다는 좋은 사례다.

⑤ BaaS도 결국 분산 시스템이다

사용자는 Appwrite에서 간단하게

account.create(...)
databases.create(...)
storage.createFile(...)

같은 API를 호출하지만 그 뒤에는

Reverse Proxy
API
Authorization
Database
Cache
Queue
Worker
Runtime
Storage
Realtime

가 연결되어 있다.

BaaS 제품이 사용자에게 복잡성을 감춰준다고 해서 시스템 자체가 단순한 것은 아니다.

Appwrite Repository는 그 복잡성을 실제 코드 수준에서 관찰할 수 있다는 점에서 공부할 가치가 있다.

14. 그렇다면 Appwrite는 어떤 프로젝트에 어울릴까?

기능 구성상 Appwrite는 다음과 같은 요구사항을 가진 애플리케이션에서 검토할 수 있다.

사용자 인증이 필요하다
+
Database가 필요하다
+
파일 Storage가 필요하다
+
Realtime 기능이 필요하다
+
Backend Function이 필요하다
+
Messaging이 필요하다

특히 Cloud 서비스뿐 아니라 Self-hosted 선택지도 필요하다면 Appwrite의 구조를 살펴볼 이유가 충분하다. Cloud와 Self-hosted 두 방식을 모두 제공한다는 점은 공식 README에서도 명시되어 있다.

반대로 Self-hosted를 선택한다면 Docker Compose에서 확인할 수 있듯 Appwrite API뿐 아니라 Redis, 데이터베이스, Worker, Executor 등 여러 인프라 컴포넌트를 함께 운영하게 된다.

15. Appwrite Repository를 공부한다면 이 순서가 좋다

처음부터 수많은 소스 파일을 읽는 것은 비효율적이다.

다음 순서가 구조를 이해하기 쉽다.

1. README.md
        ↓
2. docker-compose.yml
        ↓
3. composer.json
        ↓
4. src/Appwrite/Platform/Appwrite.php
        ↓
5. src/Appwrite/Platform/Modules
        ↓
6. 특정 HTTP Action 하나
        ↓
7. Event / Queue
        ↓
8. Worker
        ↓
9. OpenRuntimes Executor

예를 들어 Team 생성 하나만 따라가도 많은 구조를 확인할 수 있다.

POST /v1/teams
       │
       ▼
Teams/Create.php
       │
       ├── Validation
       ├── Authorization
       ├── Database
       ├── Audit Metadata
       └── Event
                │
                ▼
              Queue
                │
                ▼
              Worker

이 방식으로 하나의 요청을 끝까지 추적하면 거대한 Repository를 훨씬 빠르게 이해할 수 있다.

마무리

Appwrite를 겉에서 보면 Auth, Database, Storage를 제공하는 편리한 Backend-as-a-Service다.

하지만 내부를 살펴보면 훨씬 더 흥미롭다.

PHP + Swoole
        │
        ▼
Modular Monolith API
        │
        ▼
Redis / Queue
        │
        ▼
Independent Workers
        │
        ├── Messaging
        ├── Webhook
        ├── Functions
        ├── Build
        └── Migration
        │
        ▼
OpenRuntimes

그리고 이 모든 구성요소를 Docker 환경에서 하나의 개발 플랫폼으로 묶는다.

Appwrite에서 가장 인상적인 부분은 "기능이 많다"는 것이 아니다.

복잡한 백엔드 플랫폼을 하나의 거대한 마이크로서비스 집합으로 시작하지 않고, 핵심 API의 응집도는 유지하면서 비동기 작업과 실행 인프라를 점진적으로 분리했다는 점이다. 이 설계 배경은 Appwrite의 공식 아키텍처 설명과 현재 컨테이너 구조에서 직접 확인할 수 있다.

대규모 백엔드, BaaS, Event-driven Architecture, Worker Architecture, Serverless Runtime에 관심이 있다면 Appwrite는 단순히 사용해 볼 오픈소스를 넘어 실제 프로덕션급 백엔드 플랫폼의 구조를 공부할 수 있는 Repository로 살펴볼 만하다.

분석 정보

Repository: appwrite/appwrite
분석 기준: 2026-08-12
분석 브랜치: main
분석 시점 최신 main Commit: ac639005607c71d8a05253b38f3d7398bd298075
확인 시점 최신 정식 Release: 1.9.6
License: BSD 3-Clause
Repository: https://github.com/appwrite/appwrite

주요 분석 파일

README.md
CONTRIBUTING.md
AGENTS.md
composer.json
Dockerfile
docker-compose.yml
.env

src/Appwrite/Platform/Appwrite.php
src/Appwrite/Platform/Modules/
src/Appwrite/Event/Event.php
src/Appwrite/Platform/Modules/Teams/Http/Teams/Create.php

※ main 브랜치는 개발이 계속 진행되는 브랜치이므로 향후 디렉터리 구조, Runtime, Database 구성 및 서비스 버전은 변경될 수 있다.

GitHub - appwrite/appwrite: Appwrite® - complete cloud infrastructure for your web, mobile and AI apps. Including Auth, Databas

Appwrite® - complete cloud infrastructure for your web, mobile and AI apps. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime and more - appwrite/appwrite

github.com

안드레 카파시가 말하는 ‘어떤 분야에서 전문가가 되는 법’

행복한 수지아빠 — Mon, 10 Aug 2026 14:02:50 +0900

1. 공부부터 하지 말고, 프로젝트부터 시작한다

무언가를 처음부터 끝까지 체계적으로 전부 공부한 뒤 시작하려 하지 않는다.

대신 구체적인 프로젝트 하나를 정하고 직접 완성해본다.

진행하다가 모르는 것이 나오면 그때 필요한 내용을 배운다.

Project → 문제 발생 → 필요한 공부 → 해결 → 다음 문제

즉, 너비 우선 학습(Breadth-first)보다 깊이 우선 학습(Depth-first)이다.

예를 들어 웹 개발을 배운다면,

HTML → CSS → JS → React → DB → 서버...

를 모두 공부하고 프로젝트를 시작하는 것이 아니라,

내가 만들고 싶은 서비스 시작 → 로그인 필요 → 인증 공부 → DB 필요 → DB 공부 → 배포 필요 → 배포 공부

처럼 필요할 때 배우는 On-demand Learning을 한다.

2. 배운 것을 반드시 자기 언어로 다시 설명한다

단순히 보고 이해했다고 끝내지 않는다.

배운 것을

글로 정리하고
다른 사람에게 설명하고
블로그에 쓰거나
개발 노트로 남기고
“왜 이렇게 동작하는가?”를 자기 말로 설명한다.

설명하지 못한다면 아직 완전히 이해하지 못한 부분이 있다는 신호로 볼 수 있다.

핵심 흐름은:

배운다 → 사용한다 → 설명한다 → 다시 이해한다

이 과정을 반복하면서 지식이 단순한 정보가 아니라 자기 지식이 된다.

3. 다른 사람과 비교하지 말고 과거의 나와 비교한다

전문가와 자신의 현재 실력을 비교하면 끝이 없다.

비교 기준을

“저 사람보다 잘하나?”

가 아니라

“3개월 전의 나보다 무엇을 더 할 수 있게 되었나?”

로 잡는다.

프로젝트가 하나씩 쌓이면,

프로젝트 1 → 프로젝트 2 → 프로젝트 3 → …

각 프로젝트가 이전보다 조금 더 어려워지고, 해결할 수 있는 문제의 범위가 넓어진다.

결국 하나의 루프로 정리하면

① 만들고 싶은 프로젝트를 정한다
→ ② 일단 만든다
→ ③ 막히는 부분을 공부한다
→ ④ 직접 해결한다
→ ⑤ 배운 것을 자기 언어로 정리한다
→ ⑥ 다음에는 조금 더 어려운 프로젝트를 만든다
→ ⑦ 이전의 나와 비교한다
→ 반복

한 문장으로 요약

전문가가 되려면 모든 것을 공부하려 하지 말고, 실제 프로젝트를 깊게 파고들며 필요한 것을 그때그때 배우고, 배운 것을 자신의 언어로 설명하면서 이전의 나보다 계속 발전하면 된다.

특히 개발 공부에 적용하면 “공부 → 프로젝트”가 아니라 “프로젝트 → 공부 → 해결 → 기록 → 더 어려운 프로젝트”의 순서라는 것이 핵심입니다.

핫한 prime-agent 훝어보기

행복한 수지아빠 — Mon, 10 Aug 2026 11:02:13 +0900

(GitHub)

핵심을 한 문장으로

일반적인 코딩 에이전트가

LLM → tool call → 결과 → LLM → tool call

방식이라면 Prime Agent는 오히려

LLM → 지속되는 Python 런타임 → 코드로 도구/데이터/서브에이전트 제어 → 결과 축적 → 다음 행동

이라는 구조를 중심으로 설계했습니다. 모델에 기본적으로 노출되는 핵심 실행 환경도 persistent IPython kernel이며, 파일 읽기·수정, shell 실행, skill 호출, subagent 생성까지 Python에서 프로그래밍하듯 조합하게 합니다. (GitHub)

아키텍처를 단순화하면

                  ┌─────────────────────┐
                  │      User / TUI     │
                  └──────────┬──────────┘
                             │
                     Prime Agent Daemon
                             │
              ┌──────────────▼─────────────┐
              │       Root Agent           │
              │                            │
              │ Persistent IPython Kernel  │
              │ variables / functions      │
              │ files / shell / skills     │
              └──────┬─────────┬───────────┘
                     │         │
                rlm(...)       │ skills
                     │         │
             ┌───────▼───┐ ┌──▼──────────┐
             │ Subagent A│ │ Python Skill│
             └───────────┘ └─────────────┘
                     │
               ┌─────▼─────┐
               │Subagent A-1│
               └────────────┘

         ↓ persistent state ↓

 JSONL history
 Python state
 goals
 schedules
 heartbeat
 memories
 skills
 subagent definitions

실제 구현에서도 TUI와 실행 프로세스를 분리하고, daemon supervisor가 세션·worker·routing·복구를 관리하며, 각 worker가 root agent와 scheduler, IPython kernel, RLM children을 보유합니다. 그래서 터미널 UI를 닫아도 worker가 살아 있으면 작업이 계속될 수 있습니다. (GitHub)

1. RLM이 가장 중요한 부분

여기서 RLM은 단순히 “에이전트를 여러 개 띄운다”는 의미가 아닙니다.

Prime Agent에서 rlm(...)은 Python 함수처럼 취급됩니다.

api = await rlm(
    "API 코드를 분석하고 보안 문제를 찾아라",
    name="api-reviewer"
)

tests = await rlm(
    "테스트 커버리지를 분석해라",
    name="test-reviewer"
)

각 호출은 단순 LLM API 호출이 아니라 독립적인 Prime Agent 세션을 하나 생성합니다. child에게도 자체 context, session directory, 모델, 필요 시 IPython kernel이 있으며 결과는 단순 함수 return으로 돌려주는 게 아니라 agent-to-agent messaging을 통해 전달할 수 있습니다. (Prime Intellect)

더 중요한 것은 child가 일회용이 아니라는 점입니다.

children = await rlm.list_subagents()

로 기존 child를 다시 찾은 뒤,

await agent_message.send(
    "방금 수정한 코드까지 다시 검사해",
    receiver_role="child",
    receiver_name="api-reviewer"
)

처럼 이전에 일했던 에이전트에게 추가 작업을 줄 수 있습니다. child registry는 compaction이나 kernel restart, parent restoration 이후에도 복구하도록 설계돼 있습니다. (GitHub)

이 부분은 꽤 중요합니다.

기존 패턴이

manager
 ├─ agent A → 종료
 ├─ agent B → 종료
 └─ agent C → 종료

라면 Prime Agent가 지향하는 것은

manager
 ├─ frontend specialist ──────┐
 ├─ backend specialist ───────┤ 장기간 유지
 ├─ test specialist ──────────┤
 └─ security specialist ──────┘
             ↑
       필요할 때 재호출

에 더 가깝습니다.

2. Persistent Python이 상당히 좋은 아이디어

일반 tool-calling에서는 이런 데이터를 매번 모델 context에 다시 넣는 경우가 많습니다.

50개 파일 검색
→ 결과 30KB
→ LLM에게 전달
→ 다시 grep
→ 또 LLM에게 전달

Prime Agent에서는 Python에 그대로 남겨둘 수 있습니다.

files = ...
results = ...
failed_tests = ...
dependency_graph = ...

그리고 다음 turn에서도 해당 변수와 함수들을 사용할 수 있습니다.

문서상 Python state는 tool call과 context compaction을 넘어 유지됩니다. 즉 LLM의 context window를 작업 메모리 전체로 사용하지 않고, 상당 부분을 외부 Python environment에 밀어놓는 것입니다. (GitHub)

이게 RLM의 핵심 철학입니다.

LLM context
=
모든 정보를 집어넣는 창고

가 아니라

LLM context
=
현재 판단에 필요한 정보

Python environment
=
거대한 외부 작업 메모리

로 역할을 분리합니다.

장시간 코딩 작업에서는 상당히 합리적인 설계입니다.

3. “Self-improving”의 정확한 의미

여기가 가장 오해하기 쉽습니다.

Prime Agent가 작업하면서 GPT나 Claude의 neural weights를 재학습시키는 것은 아닙니다.

대신 Continual Harness라는 별도의 상태를 변경합니다.

공식 설명에서는 이를

H = (ρ, G, K, M)

ρ = prompts
G = subagents
K = skills
M = memory

형태로 정의하고 있습니다. 이 상태에 대해 create/read/update/delete가 가능합니다. (Prime Intellect)

예를 들어 에이전트가 여러 번 작업해보니

우리 프로젝트에서는 migration 수정 후
반드시 pnpm prisma generate를 실행해야 한다.

라는 패턴을 발견했다고 합시다.

처음에는 그냥 대화 중 발견한 사실입니다.

그러다가 /refine이 trajectory를 분석해 이것을

Memory
또는
Prompt Note
또는
Skill

로 승격시킬 수 있습니다.

그리고 반복 작업이라면:

migration-check/
 ├── SKILL.md
 ├── pyproject.toml
 └── src/
     └── migration_check/
         └── __init__.py

같은 Python-backed skill까지 만들 수 있습니다. Prime Agent는 instruction-only SKILL.md뿐 아니라 실제 Python package를 persistent IPython에 설치하는 형태도 공식 지원합니다. (GitHub)

그래서 정확하게 표현하면

모델이 개선되는 것이 아니라 에이전트의 작업 환경과 operating procedure가 경험을 통해 개선됩니다.

라고 보는 게 맞습니다.

저는 오히려 이 방식이 실용적으로 중요하다고 봅니다. 모델 fine-tuning 없이도 실제 프로젝트에서 반복적으로 발생하는 노하우를 축적할 수 있기 때문입니다.

4. Continual Harness가 재미있는 이유

일반적인 AGENTS.md, CLAUDE.md, SKILL.md 방식은 사람이 관리합니다.

사람
↓
실수 발견
↓
AGENTS.md 수정
↓
다음 작업부터 개선

Prime Agent는 이 루프의 일부를 agent에게 넘기려 합니다.

Agent 작업

       ↓

성공 / 실패 trajectory

       ↓

/refine

       ↓

┌──────────────┐
│ Prompt Note  │
│ Memory       │
│ Skill        │
│ Subagent Spec│
└──────────────┘

       ↓

다음 작업

       ↓

더 나은 Harness

/refine은 현재 trajectory를 보고 가능한 한 작은 CRUD 변경을 적용하도록 설계되어 있으며, base system prompt 자체는 수정하지 않습니다. refinement history를 남기고 이전 상태로 rollback하는 구조도 있습니다. (Prime Intellect)

따라서 이것은 사실상 “agent-level continual learning”을 weights 밖에서 구현하려는 접근법이라고 이해하면 좋습니다.

5. 장시간 자율 작업은 꽤 제대로 설계되어 있습니다

Prime Agent에는 서로 다른 역할의 기능이 따로 존재합니다.

기능역할

Persistent Goal	끝날 때까지 목표 유지
Autonomous Mode	다음 작업을 계속 실행
Heartbeat	일정 간격으로 agent 깨우기
Schedule	특정 시점/cron 실행
Subagent	병렬 전문 작업
Compaction	오래된 context 압축
JSONL persistence	세션 기록
Daemon	UI와 실행 분리

예를 들어 heartbeat는 사용자용 /heartbeat와 agent가 직접 만드는 rlm_heartbeat가 분리되어 있습니다. prime-agent schedule은 one-time 또는 cron prompt를 별도로 예약할 수 있습니다. (GitHub)

따라서 이런 구조가 가능합니다.

Goal:
"서비스 전체 성능을 개선하고 테스트까지 통과시켜라."

09:00
main agent 시작

09:05
├── backend-agent
├── frontend-agent
├── db-agent
└── benchmark-agent

09:30 heartbeat
"benchmark 결과 확인"

10:00
benchmark-agent → main
"API P95 820ms"

main
→ backend-agent
"DB query 최적화"

11:00
test gate 실행

FAILED

main
→ 수정

12:00
test gate

PASSED

goal.complete()

Autonomous mode에는 max turns, token budget, wall-clock timeout과 quality gate를 설정할 수 있고, gate가 실패하면 그 출력을 agent에게 다시 넘겨 후속 작업을 수행하게 할 수 있습니다. (GitHub)

이 부분이 단순 cron 기반 AI script와 큰 차이입니다.

6. Codex / Claude Code와 가장 다른 부분

제가 보기에는 차이를 이렇게 잡는 것이 가장 정확합니다.

Codex / Claude Code 계열Prime Agent

중심 abstraction	Agent + tools	Agent + persistent REPL
tool 사용	개별 tool calling	Python program
subagent	task delegation	persistent agent process
context	모델 context 중심	context + Python state
장기 작업	continuation 중심	daemon + goal + schedule + heartbeat
학습	rules/memory	Continual Harness CRUD
skill	instructions/scripts	Python package 가능
A2A	제한적	native messaging

[Inference] 그래서 Prime Agent의 진짜 경쟁 포인트는 모델 자체의 코딩 능력보다 “에이전트를 운영하는 OS/runtime”에 있습니다. 이 해석은 위 아키텍처와 공식 문서에 나타난 설계 패턴을 기반으로 한 것입니다. (GitHub)

7. 의외로 모델 선택도 자유롭습니다

현재 공식 provider 문서에는 OpenAI, Anthropic, Gemini, DeepSeek, Groq, Cerebras, OpenRouter, Fireworks, MiniMax, Kimi, Xiaomi MiMo 등 상당히 많은 provider가 나옵니다.

특히 OAuth 방식으로 ChatGPT Plus/Pro(Codex), Claude Pro/Max, GitHub Copilot도 지원한다고 문서화돼 있습니다. (GitHub)

즉:

Prime Agent
       │
       ├─ GPT
       ├─ Claude
       ├─ Gemini
       ├─ GLM
       ├─ MiniMax
       ├─ Kimi
       └─ OpenRouter models

같은 harness 실험이 가능합니다.

8. 주의할 부분도 큽니다

가장 큰 문제는 보안입니다.

Prime Agent 공식 문서도 IPython kernel과 worker가 security sandbox가 아니라고 명시하고 있습니다. 모델이 생성한 Python과 shell command가 기본적으로 사용자 OS 권한으로 실행됩니다. (GitHub)

따라서:

Prime Agent
↓
persistent Python
↓
shell
↓
filesystem
↓
skills
↓
subagents

처럼 agent의 힘이 커질수록 prompt injection이나 악성 repository, 악성 skill의 피해 범위도 커질 수 있습니다.

특히 장시간 autonomous mode를 쓸 거라면 Docker/VM/devcontainer 같은 별도 sandbox 안에서 돌리는 방식이 더 적합하다고 판단합니다. [Inference] 이는 공식 문서가 untrusted repository/instruction에 external sandbox 또는 restricted environment 사용을 권고한다는 점을 바탕으로 한 운영상 권고입니다. (GitHub)

9. 벤치마크는 흥미롭지만 아직 조심해서 봐야 합니다

Prime Intellect는 자체 발표에서 Prime Agent를 Opus 5, GPT-5.6 Sol, GLM-5.2 등과 조합해 장문맥 benchmark를 테스트했고, 여러 항목에서 native harness와 경쟁하거나 앞서는 결과를 보고했습니다. ARC-AGI-3에서도 높은 결과를 발표했습니다. (Prime Intellect)

그러나 이것은 Prime Intellect 자체 평가 결과입니다. 독립적인 대규모 재현 결과와 동일하게 취급해서는 안 됩니다. 또한 회사도 현재 모델들이 Prime Agent harness 자체를 대상으로 훈련된 것은 아니라고 밝히고 있습니다. (Prime Intellect)

10. 이 프로젝트에서 제가 가장 높게 보는 부분

[Inference] 개인적으로 기술적으로 가장 중요한 순서를 꼽으면 Persistent REPL → persistent subagent → Continual Harness → daemon/scheduler 순입니다. 이는 기능의 기반 의존관계를 기준으로 한 판단입니다.

특히 이 조합:

Persistent Python
       +
Persistent Subagents
       +
Persistent Memory
       +
Executable Skills
       +
Heartbeat
       +
Goal
       +
Scheduler

이 만들어내는 결과는 단순히

“AI가 코드를 잘 짠다.”

가 아니라

“AI 개발팀이 프로젝트 안에 계속 상주한다.”

에 가까워집니다.

예를 들어 하나의 프로젝트에:

main-agent
│
├── architect
├── backend
├── flutter
├── security
├── test
└── devops

를 장기간 유지하면서 각 agent에게 프로젝트별 memory와 skill을 축적시키는 구조입니다.

이게 잘 발전하면 Claude Code/Codex의 경쟁 제품보다는 오히려 AI Agent Runtime / Agent OS / autonomous engineering runtime이라는 분류가 더 적합해질 가능성이 있습니다. [Inference] 이는 현재 daemon, persistent session, RLM child lifecycle, scheduling, Continual Harness 구조를 종합한 판단입니다. (GitHub)

결론

주목할 가치가 상당히 큰 레포입니다. 특히 RLM = recursive call 정도로 보면 핵심을 놓칩니다. 진짜 포인트는 LLM이 Python을 자기 작업용 컴퓨터처럼 사용하고, 그 안에서 다른 LLM 세션까지 함수처럼 조직하며, 수행 과정에서 얻은 노하우를 memory/skill/subagent spec으로 축적하는 것입니다. (GitHub)

그리고 Prime Agent가 말하는 “self-improving”도 모델 자체 self-training이 아니라 harness의 self-improvement라고 이해하는 게 정확합니다.

OpenAI Agents SDK

행복한 수지아빠 — Mon, 10 Aug 2026 10:30:17 +0900

챗봇 하나를 만드는 일과 인공지능(AI) 에이전트 팀을 만드는 일은 다르다.

챗봇은 질문을 받고 답을 돌려주면 끝난다. 에이전트는 다르다. 필요한 도구를 고르고, 작업 결과를 다시 읽고, 다른 전문가에게 일을 넘긴 뒤 조건을 만족할 때까지 다음 행동을 결정해야 한다. 정작 어려운 부분은 모델 호출보다 그 주변의 실행 흐름에 있다.

OpenAI Agents SDK는 바로 이 흐름을 파이썬 코드로 다루기 위한 오픈소스 소프트웨어 개발 키트(Software Development Kit, SDK)다. 거대한 워크플로 엔진을 먼저 배우지 않아도 Agent, Runner, 도구, handoff, guardrail 같은 몇 가지 개념만으로 에이전트 애플리케이션을 구성할 수 있다.

이 프로젝트를 한 문장으로 정리하면 이렇다.

OpenAI Agents SDK는 AI가 답변만 생성하는 단계를 넘어, 도구를 사용하고 다른 에이전트와 협업하며 작업을 끝낼 때까지 실행하는 런타임이다.

모델보다 중요한 것은 실행 흐름이다

일반적인 대규모 언어 모델(Large Language Model, LLM) 애플리케이션은 입력을 모델에 보내고 결과를 받는다.

에이전트 애플리케이션이라면 그 사이에 여러 단계가 들어간다.

사용자 입력
  ↓
에이전트가 다음 행동 판단
  ↓
도구 실행 또는 다른 에이전트로 handoff
  ↓
실행 결과를 다시 모델에 전달
  ↓
가드레일과 출력 형식 검증
  ↓
최종 결과 또는 다음 반복

이 반복 구조를 직접 구현하려면 도구 호출, 오류 처리, 대화 이력, 상태 저장, 스트리밍, 실행 중단과 재개까지 관리해야 한다. Agents SDK의 Runner가 이 반복을 맡는다. 개발자에게 남는 일은 각 에이전트의 역할과 사용할 수 있는 도구를 선언하는 것이다.

핵심은 모델에게 더 긴 프롬프트를 주는 데 있지 않다. 모델이 어떤 범위 안에서 무엇을 할 수 있는지 코드로 정의하는 것, 그것이 출발점이다.

네 가지 개념으로 시작한다

1. Agent: 역할과 권한을 가진 작업자

Agent는 단순한 모델 별칭이 아니다. 역할과 실행 조건을 다음과 같이 한데 묶는다.

이름과 업무 지침
사용할 모델
호출할 수 있는 도구
업무를 넘길 수 있는 다른 에이전트
입력과 출력을 검사하는 가드레일
구조화된 출력 타입

가장 작은 에이전트부터 살펴보자.

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="질문에 짧고 정확한 한국어로 답하세요.",
)

result = Runner.run_sync(
    agent,
    "멀티 에이전트 시스템이 필요한 이유를 한 문장으로 설명해 줘.",
)

print(result.final_output)

동기 실행이 필요하지 않다면 비동기 Runner.run()이나 스트리밍 실행을 선택할 수 있다. 네트워크 요청과 도구 실행이 많은 실제 서비스에서는 비동기 방식이 자연스럽다.

2. Tool: 답변을 행동으로 바꾸는 연결점

에이전트가 사내 데이터 조회, 계산, 검색, 파일 처리 같은 일을 하려면 도구가 필요하다. Agents SDK는 파이썬 함수의 타입 정보를 읽어 도구 스키마를 만들고, Pydantic 기반 검증을 적용한다.

from agents import Agent, Runner
from agents.decorators import tool


@tool
def get_order_status(order_id: str) -> str:
    """주문 번호로 현재 배송 상태를 조회한다."""
    return f"{order_id}: 배송 준비 중"


agent = Agent(
    name="Order Support",
    instructions="주문 문의를 처리하세요. 필요한 경우 주문 조회 도구를 사용하세요.",
    tools=[get_order_status],
)

result = Runner.run_sync(agent, "ORDER-1024의 상태를 확인해 줘.")
print(result.final_output)

도구는 일반 함수에만 머물지 않는다. AI 애플리케이션과 외부 도구를 표준 방식으로 연결하는 Model Context Protocol(MCP) 서버, OpenAI 호스팅 도구, 다른 에이전트, 그리고 실험적인 로컬 Codex CLI까지 연결할 수 있다.

3. Handoff: 적합한 전문가에게 실행권 넘기기

멀티 에이전트 구성에서 중요한 것은 에이전트의 수가 아니라 책임의 경계다.

결제 문의와 기술 장애를 하나의 프롬프트에 모두 넣을 수도 있다. 하지만 업무별 정책, 도구, 출력 형식이 달라진다면 전문 에이전트를 나누는 편이 관리하기 쉽다.

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing Specialist",
    handoff_description="결제, 청구서, 환불 문의를 담당합니다.",
    instructions="결제 정책에 따라 문의를 처리하세요.",
)

technical_agent = Agent(
    name="Technical Specialist",
    handoff_description="로그인, 오류, 성능 문제를 담당합니다.",
    instructions="증상을 확인하고 재현 가능한 진단 절차를 안내하세요.",
)

triage_agent = Agent(
    name="Triage",
    instructions="문의 내용을 분류해 적합한 전문가에게 넘기세요.",
    handoffs=[billing_agent, technical_agent],
)

result = Runner.run_sync(
    triage_agent,
    "결제는 됐는데 구독 기능이 활성화되지 않았어요.",
)

print(result.final_output)

Handoff가 일어나면 다음 에이전트가 실행 흐름을 이어받는다. 반대로 총괄 에이전트가 하위 에이전트의 결과를 받아 직접 최종 답변을 작성해야 한다면, 전문 에이전트를 ‘agent as tool’ 형태로 등록할 수 있다.

4. Guardrail: 모델 앞뒤에 세우는 검증선

가드레일은 모델이 스스로 지켜 주기를 기대하는 프롬프트 문장이 아니다. 애플리케이션 실행 경로에 포함되는 검사다.

예를 들어 다음 조건을 코드로 분리할 수 있다.

입력에 개인정보나 금지된 요청이 포함됐는가
사용자의 질문이 에이전트의 업무 범위에 속하는가
결과가 요구한 타입과 필드를 만족하는가
도구에 전달할 인자가 정책을 위반하지 않는가
특정 조건에서는 사람의 승인이 필요한가

검증에 실패하면 실행을 중단하거나 별도 처리 경로로 보낼 수 있다. 생성형 모델의 불확실성을 없애지는 못하지만, 실패를 발견하고 통제할 위치를 만들어 준다.

실제 서비스에 필요한 주변 기능

Agents SDK의 강점은 멀티 에이전트 데모를 만드는 데서 끝나지 않는다. 운영 환경에 필요한 기능도 실행 런타임 주변에 모여 있다.

세션과 대화 상태

여러 실행 사이에서 대화 이력을 유지할 수 있다. 저장 방식도 하나로 고정되지 않는다. 기본 SQLite 구성뿐 아니라 SQLAlchemy, Redis, 암호화 세션과 사용자 정의 저장소를 선택할 수 있다.

세션은 ‘AI의 기억’이라는 추상적인 표현보다 다음 실행에 어떤 대화 상태를 다시 공급할 것인가에 가깝다. 서비스에서는 사용자별 격리, 보존 기간, 암호화와 삭제 정책을 함께 설계해야 한다.

Human-in-the-loop

환불, 배포, 파일 삭제, 외부 메시지 전송처럼 되돌리기 어려운 행동은 사람의 승인을 기다리게 만들 수 있다. 실행을 중단하고 상태를 저장한 뒤, 승인 또는 거절 결과를 받아 이어서 실행하는 방식이다.

이 기능의 목적은 AI가 모든 것을 자동 처리하게 만드는 데 있지 않다. 자동화할 부분과 사람이 책임질 부분을 분리하는 장치에 가깝다.

Tracing

에이전트가 어떤 판단을 거쳐 어느 도구를 호출했고, 언제 다른 에이전트로 넘어갔는지 추적할 수 있다. 모델 호출 시간, 도구 실행, 오류와 토큰 사용량을 살펴보며 병목과 실패 지점을 찾는 데 유용하다.

멀티 에이전트 시스템은 최종 답변만 봐서는 문제의 원인을 찾기 어렵다. 추적 정보가 있다면 잘못된 분류인지, 도구 오류인지, handoff 이후의 문맥 손실인지 구분할 수 있다.

Sandbox Agent

코드 저장소를 읽고 명령을 실행하거나 파일을 수정하는 작업에는 실제 작업공간이 필요하다. SandboxAgent는 로컬 Unix 환경, Docker 또는 호스팅 샌드박스와 연결해 격리된 작업을 수행한다.

파일 접근 범위, 네트워크 사용, 명령 실행 권한은 명확히 제한해야 한다. 일반 텍스트 에이전트에 셸 권한을 무심코 붙이지 않고 작업공간과 권한을 별도 경계로 다루는 이유가 여기에 있다.

Realtime Agent와 Voice Pipeline

저지연 음성 대화에는 WebSocket 기반 RealtimeAgent를 사용할 수 있다. 음성 인식, 일반 에이전트 실행, 음성 합성을 단계별로 조합하고 싶다면 VoicePipeline을 선택할 수 있다.

두 기능은 비슷해 보이지만 구조가 다르다. Realtime Agent는 지속적인 실시간 세션에 가깝다. Voice Pipeline은 음성 인식(Speech-to-Text, STT) → 에이전트 → 음성 합성(Text-to-Speech, TTS) 처리 흐름에 가깝다.

OpenAI 모델만 사용할 수 있는 것은 아니다

프로젝트 README는 이 SDK를 provider-agnostic, 즉 특정 모델 제공자에만 묶이지 않는 구조로 설명한다. OpenAI Responses API(Application Programming Interface)와 Chat Completions API뿐 아니라 OpenAI 호환 엔드포인트와 외부 어댑터도 연결할 수 있다는 뜻이다.

예를 들어 DeepSeek API를 기본 모델 클라이언트로 지정할 수 있다.

import os

from openai import AsyncOpenAI
from agents import (
    Agent,
    Runner,
    set_default_openai_client,
    set_tracing_disabled,
)

client = AsyncOpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

set_default_openai_client(
    client,
    use_for_tracing=False,
)
set_tracing_disabled(True)

agent = Agent(
    name="DeepSeek Assistant",
    instructions="정확하고 간결한 한국어로 답하세요.",
    model="deepseek-v4-flash",
)

result = Runner.run_sync(agent, "에이전트와 챗봇의 차이를 설명해 줘.")
print(result.final_output)

위 코드는 연결 형태를 보여 주는 예제이며, 이 글을 작성한 환경에서는 실제 DeepSeek API 키를 사용한 호출까지 검증하지 않았다.

2026년 8월 10일 기준으로 DeepSeek의 Responses API는 deepseek-v4-flash를 지원하지만 일부 OpenAI 기능과 완전히 같지는 않다. previous_response_id, 서버 측 conversation 저장, 파일·이미지 입력, MCP와 일부 호스팅 도구에는 제약이 있다. 모델 제공자를 바꿀 때는 ‘요청 형식이 비슷하다’는 사실과 ‘기능이 동일하다’는 판단을 구분해야 한다.

설치하고 첫 실행까지

이 저장소의 현재 패키지는 Python 3.10 이상을 요구한다. 아래 절차는 macOS 또는 Linux의 표준 셸 환경을 기준으로 한다.

1. 가상환경과 패키지 준비

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install openai-agents

확인:

python -c "import agents; print(agents.__version__)"

버전 번호가 출력되면 패키지를 불러올 수 있는 상태다.

실패한다면 현재 셸에서 .venv가 활성화됐는지, python --version이 3.10 이상인지 먼저 확인한다.

2. API 키 설정

export OPENAI_API_KEY="발급받은_API_키"

실제 키를 소스 코드나 Git 저장소에 저장하지 않는다. 서비스 환경에서는 운영체제의 비밀 저장소나 배포 플랫폼의 secret 기능을 사용한다.

3. 예제 실행

다음 내용을 hello_agent.py로 저장한다.

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="친절하고 정확한 한국어로 답하세요.",
)

result = Runner.run_sync(agent, "오늘 해야 할 일을 세 단계로 정리해 줘.")
print(result.final_output)

실행:

python hello_agent.py

정상이라면 모델이 생성한 답변이 터미널에 출력된다.

Missing credentials 오류가 나오면 OPENAI_API_KEY가 현재 셸에 설정됐는지 확인한다. 401 오류가 나오면 키의 유효성과 API 프로젝트 권한을 확인한다.

이 SDK가 잘 맞는 경우

다음 조건이라면 Agents SDK의 장점이 분명하다.

모델이 여러 도구를 선택하며 반복적으로 작업해야 한다
역할이 다른 전문 에이전트에게 업무를 위임해야 한다
입력, 출력과 도구 호출을 별도로 검증해야 한다
대화 상태와 장기 실행을 관리해야 한다
중요한 행동 전에 사람의 승인이 필요하다
실행 경로를 추적하고 디버깅해야 한다
실제 파일과 명령을 다루는 격리 작업공간이 필요하다

반대로 한 번의 요청으로 짧은 텍스트를 생성하고 끝나는 기능이라면 Responses API나 Chat Completions API를 직접 호출하는 편이 단순할 수 있다. 에이전트 수가 많다고 좋은 구조가 되는 것도 아니다. 책임과 권한이 분리되지 않은 에이전트는 이름만 여러 개인 하나의 복잡한 프롬프트가 되기 쉽다.

AI 팀을 만든다는 것

멀티 에이전트 시스템을 소개할 때는 종종 조직도 같은 그림이 먼저 등장한다. 총괄 에이전트 아래에 조사, 개발, 검토 에이전트를 배치한 모습은 제법 그럴듯하다.

그렇다면 에이전트를 많이 배치할수록 결과도 좋아질까? 실제 품질을 결정하는 것은 숫자가 아니다.

누가 어떤 정보를 볼 수 있는지, 어떤 도구를 실행할 수 있는지부터 정해야 한다. 언제 다른 에이전트에게 넘길지, 실패하면 어디에서 중단할지, 마지막 결과를 누가 책임질지도 빠질 수 없다. OpenAI Agents SDK는 이런 결정을 파이썬 코드로 옮길 수 있게 해 준다.

복잡한 프레임워크 없이 시작할 수 있다는 말이 설계까지 필요 없다는 뜻은 아니다. 오히려 작은 문법으로 책임과 경계를 또렷하게 드러낼 수 있다는 뜻에 가깝다.

AI에게 일을 시키는 시대를 지나 AI 팀을 운영하려 한다면, 이 프로젝트는 꽤 현실적인 출발점이다.

참고 자료

검증 기준

이 글의 프로젝트 기능과 설치 조건은 2026년 8월 10일에 다음 로컬 소스를 기준으로 확인했다.

저장소 브랜치: main
확인 커밋: 54cc7d93
패키지 버전: openai-agents 0.19.4
패키지 요구 조건: Python 3.10 이상
로컬 확인 환경: macOS, Python 3.13.7, uv

저장소 설치와 Python import는 로컬에서 검증했다. 글에 포함한 OpenAI 및 DeepSeek API 호출 예제는 실제 자격 증명을 사용해 실행하지 않았으므로 API 응답 결과는 미검증이다.

메인은 GPT-5.6, 서브에이전트는 DeepSeek V4 Flash로 설정하기

행복한 수지아빠 — Thu, 6 Aug 2026 13:41:49 +0900

GPT-5.6은 감독하고, DeepSeek V4 Flash 서브에이전트가 작업하는 Codex 구성법

이 구성에서 실제 일은 deepseek_v4_flash 자식이 합니다. 자식은 요청을 받아 파일을 조사하고, 필요한 코드를 바꾸고, 관련 검증까지 수행합니다. 메인 GPT-5.6은 같은 결과물을 다시 작성하지 않고 작업 범위·변경 내역·검증 근거를 확인한 뒤 승인하거나 보완 작업만 지시합니다.

이 글은 Codex의 메인을 GPT-5.6으로 유지하면서, deepseek_v4_flash라는 전용 자식 worker가 DeepSeek V4 Flash로 작업을 소유하게 만드는 방법을 다룹니다. 부모는 조율자와 최종 검토자이고, 자식은 실행자입니다.

핵심은 API 키를 에이전트 파일마다 복사하지 않는 것입니다. 키는 provider에 한 번만 연결하고, 서브에이전트는 그 provider를 명시적으로 선택합니다. Codex는 커스텀 provider와 커스텀 에이전트 파일을 지원합니다. Codex 설정 레퍼런스, 서브에이전트 문서

이 글의 예시는 macOS/Linux 기준입니다. API 키를 문서, Git 저장소, 스크린샷, 채팅 로그에 남기지 마세요. 이미 노출된 키라면 먼저 폐기하고 새 키를 발급받는 편이 안전합니다.

먼저 확인할 것

이 구성에는 다음이 필요합니다.

최신 Codex
ChatGPT 또는 OpenAI 인증으로 동작하는 GPT-5.6 메인 모델
DeepSeek API 키와 사용 가능한 잔액/권한
deepseek-v4-flash 모델 접근 권한

DeepSeek의 현재 모델 ID와 기본 API URL은 공식 모델 문서에서 확인하는 편이 좋습니다. 모델 이름이나 API 형식은 바뀔 수 있으므로, 다른 블로그의 값을 그대로 복사하기보다 공식 문서를 우선합니다. DeepSeek Models & Pricing

1. 설정부터 백업한다

provider 설정은 사용자 전역 설정에 들어가므로, 먼저 원본을 따로 보관합니다. 아래 명령은 삭제하거나 덮어쓰지 않고 복사본만 만듭니다.

mkdir -p ~/.codex/backups
backup_stamp="$(date +%Y%m%d-%H%M%S)"
backup_dir="$HOME/.codex/backups/before-deepseek-$backup_stamp"

mkdir -p "$backup_dir"
cp -p ~/.codex/config.toml "$backup_dir/config.toml"

if [ -d ~/.codex/agents ]; then
  ditto ~/.codex/agents "$backup_dir/agents"
fi

chmod -R go-rwx "$backup_dir"

config.toml에 토큰이 직접 들어 있을 가능성이 있다면 백업도 민감 정보입니다. 클라우드 드라이브나 Git에 올리지 말고, 소유자만 읽을 수 있도록 둡니다.

2. API 키는 provider에 한 번만 연결한다

~/.codex/config.toml의 기존 메인 모델 설정은 유지합니다. 그 아래에 DeepSeek provider만 추가합니다.

# 메인 모델은 기존 GPT-5.6/OpenAI 설정을 그대로 둡니다.
model = "gpt-5.6-sol"
model_provider = "openai"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"

env_key는 키 자체가 아니라 환경 변수의 이름입니다. Codex의 provider 설정은 환경 변수로 API 키를 받도록 지원하며, 직접 토큰을 TOML에 쓰는 방식보다 안전합니다. Codex provider 설정

macOS 데스크톱 앱이 키를 읽도록 하려면 현재 로그인 세션에 환경 변수를 설정한 뒤 Codex를 완전히 재시작합니다.

launchctl setenv DEEPSEEK_API_KEY "발급받은_키"

이 명령은 현재 로그인 세션을 위한 설정입니다. 영구 보관이 필요하다면 운영체제 키체인이나 조직의 비밀 관리 방식을 사용하면 됩니다. 셸 시작 파일에 실제 키를 평문으로 적는 방법은 피하는 것이 좋습니다.

3. 자식에게 실행권한을 주고, 부모는 감독만 하게 한다

agents.default_subagent_model만 바꾸면 모델 이름만 기본값으로 바뀌고 provider까지 안전하게 고정되지 않습니다. 메인 OpenAI provider로 DeepSeek 모델을 호출하는 실수를 피하려면, provider를 함께 지정한 커스텀 에이전트를 만듭니다.

~/.codex/agents/deepseek-v4-flash.toml 파일을 만듭니다.

name = "deepseek_v4_flash"
description = "Fast DeepSeek V4 Flash worker for bounded implementation, documentation, and verification tasks."
model = "deepseek-v4-flash"
model_provider = "deepseek"
sandbox_mode = "workspace-write"

developer_instructions = """
Own the bounded task delegated by the parent from inspection through
implementation and focused verification. Modify only files needed for the task,
preserve unrelated user changes, and never access or change credentials. Return
a concise summary of changed files, verification evidence, and any limitation.
"""

workspace-write는 자식에게 현재 작업공간 안에서 구현할 권한을 줍니다. 자식은 요청을 받아 구현과 검증을 마칠 때까지 작업을 소유하고, 부모는 결과가 요구사항과 맞는지 확인합니다. 자격 증명·전역 설정·배포 권한은 자식의 범위에서 제외하는 편이 좋습니다.

Codex는 ~/.codex/agents/ 아래의 각 TOML 파일을 커스텀 에이전트로 로드하며, 그 파일의 model 설정은 부모 설정보다 우선합니다. 커스텀 에이전트 설정 방식

4. 부모는 작업을 넘기고, 결과만 검토한다

Codex를 완전히 종료한 뒤 다시 엽니다. 부모에게는 다음처럼 역할을 분명히 요청합니다. 부모는 직접 파일을 고치지 않고, 자식이 작업한 결과와 검증 기록을 검토합니다.

deepseek_v4_flash 자식에게 이 작업을 전부 맡겨 주세요.
자식이 관련 파일을 조사하고 구현한 뒤, 필요한 테스트를 실행해 결과를 보고하게 하세요.
부모는 파일을 직접 수정하지 말고 변경 파일, 테스트 결과, 요구사항 충족 여부만 검토해 승인 또는 보완 사항을 알려 주세요.

자식에게 원래 사용자 요청 또는 그 요청을 정확히 요약한 작업 지시가 전달돼야 합니다. 부모가 결과물을 대신 쓸 필요는 없지만, 자식이 무엇을 완성해야 하는지 알 수 있어야 하기 때문입니다.

부모가 확인할 항목은 세 가지면 충분합니다.

자식이 수정한 파일이 작업 범위 안에 있는가
자식이 실행한 검증이 변경 내용과 맞는가
결과가 사용자의 요청을 충족하는가

5. provider와 worker를 각각 검증한다

먼저 DeepSeek provider 자체를 확인합니다.

codex exec --strict-config --sandbox workspace-write \
  --model deepseek-v4-flash \
  --config 'model_provider="deepseek"' \
  'Create a small Markdown file, read it back, and report the title and line count.'

성공 기준은 자식이 파일을 만들고, 스스로 읽어 확인한 결과를 반환하는 것입니다. 이후 부모가 같은 파일을 읽어 제목·줄 수·변경 범위를 독립적으로 확인하면 작성과 감독이 분리됩니다.

커스텀 에이전트를 통한 자동 위임은 Codex 버전과 실행 환경에 따라 작업 본문 전달이 실패할 수 있습니다. 실제 업무에 쓰기 전에 반드시 자식이 전달받은 작업을 자신의 말로 요약하고, 해당 파일을 실제로 수정·검증했는지 확인하세요. 작업 지시가 비어 있다면 provider 문제가 아니라 handoff 문제이므로, 성공한 것처럼 다음 단계로 넘어가면 안 됩니다.

6. 문제가 생기면 원본으로 되돌린다

테스트가 실패했거나 메인 모델 선택이 달라졌다면, Codex를 종료한 상태에서 백업본의 config.toml과 agents 폴더를 복원합니다. 복원 전 현재 파일도 별도로 복사해 두면 원인을 비교할 수 있습니다.

복원 후에는 codex doctor로 다음 두 가지를 확인합니다.

config.toml parse ok
메인 모델이 의도한 GPT-5.6과 openai provider로 표시되는지

DeepSeek 모델을 못 찾는다는 메타데이터 경고가 나올 수 있습니다. 호출이 성공하더라도 복잡한 도구 사용이나 장기 작업에서 동작이 달라질 수 있으므로, 처음에는 작은 기능 하나처럼 검증 범위가 분명한 작업부터 맡기는 편이 안전합니다.

어떤 작업을 DeepSeek 서브에이전트에 맡길까

DeepSeek 자식이 소유할 작업	GPT-5.6 부모가 관리할 작업
관련 코드 조사, 구현, 단위·통합 테스트	요구사항을 작업 단위로 나누기
문서 작성과 코드 정리	변경 범위와 사용자 의도 대조
오류 재현, 원인 분석, 수정안 적용	테스트 근거와 회귀 위험 검토
반복되는 기능 작업	보안·배포·데이터 변경의 최종 승인

부모가 자식의 결과를 다시 구현하면 분업의 이점이 사라집니다. 부모는 결과를 믿는 것이 아니라, 변경 파일과 검증 근거를 살펴 결과를 판정합니다. 이 역할 분리가 비용을 줄이면서도 품질을 통제하는 핵심입니다.

마무리

이 구성의 목표는 GPT-5.6을 구현자로 쓰는 것이 아닙니다. GPT-5.6은 맥락·우선순위·최종 책임을 유지하고, DeepSeek V4 Flash 자식은 실제 작업과 검증을 끝까지 수행합니다. provider에는 키를 한 번만 연결하고, 에이전트 파일에는 worker의 역할·모델·권한만 남기면 관리와 복구가 단순해집니다.

Cerebras는 어떻게 사내 지식 검색 시스템을 구축했을까?

행복한 수지아빠 — Wed, 5 Aug 2026 16:29:57 +0900

PostgreSQL 하나로 구현한 엔터프라이즈 RAG 아키텍처 분석

최근 생성형 AI가 기업 업무에 빠르게 도입되면서, 사내 문서와 대화 기록을 AI가 검색하고 활용할 수 있도록 만드는 엔터프라이즈 지식 검색 시스템이 주목받고 있다.

그러나 실제 기업 환경에서 RAG 시스템을 운영하는 일은 생각보다 단순하지 않다.

기업의 지식은 한곳에 정리되어 있지 않기 때문이다.

업무 대화는 Slack에서 이루어진다.
소스 코드는 GitHub에 저장된다.
프로젝트 일정과 이슈는 Jira에서 관리된다.
공식 문서는 Google Drive나 Notion에 존재한다.
중요한 결정은 회의록이나 이메일에 남는다.

이처럼 데이터가 여러 서비스에 분산된 상황에서, AI가 사용자의 질문에 정확한 답을 제공하려면 단순한 벡터 검색 이상의 설계가 필요하다.

이번 글에서는 AI 반도체 기업 Cerebras가 공개한 사내 지식 검색 시스템인 Cerebras Knowledge의 구조를 살펴본다.

특히 다음 네 가지를 중심으로 분석한다.

전용 벡터 데이터베이스 없이 PostgreSQL을 선택한 이유
Slack 데이터를 검색 가능한 지식으로 변환하는 방법
키워드·벡터·희소성·신선도를 결합한 하이브리드 검색
인간용 UI와 AI 에이전트용 MCP 도구를 분리한 설계

1. Cerebras Knowledge란 무엇인가?

Cerebras Knowledge는 Cerebras 내부의 여러 데이터 소스를 통합 검색하기 위해 구축된 사내 지식 시스템이다.

제공된 기사에 따르면 이 시스템은 출시 후 약 3개월 만에 하루 15,000건 이상의 질문을 처리하는 수준으로 사용되고 있다.

질문을 보내는 주체도 사람만이 아니다.

일반 직원
개발자
사내 자동화 시스템
AI 에이전트
코딩 에이전트

즉, Cerebras Knowledge는 단순한 사내 챗봇이 아니라 인간과 AI가 함께 사용하는 조직 지식 인프라에 가깝다.

일반적인 사내 RAG 시스템은 다음과 같은 흐름을 따른다.

Slack · GitHub · Jira · 문서
        ↓
데이터 수집 및 청크 분할
        ↓
임베딩 생성
        ↓
벡터 데이터베이스 저장
        ↓
유사도 검색
        ↓
LLM 답변 생성

Cerebras의 구조도 큰 흐름은 비슷하다.

다만 다음 두 가지에서 차별점이 있다.

첫째, Pinecone이나 전용 검색 클러스터 대신 PostgreSQL을 중심으로 시스템을 구성했다.

둘째, Slack 메시지를 그대로 임베딩하지 않고, 검색에 적합한 형태로 정규화한 후 저장했다.

2. 왜 사내 지식 검색은 어려운가?

2.1 지식은 작성하기 편한 장소에서 만들어진다

많은 기업이 지식 관리 문제를 해결하기 위해 다음과 같은 목표를 세운다.

모든 정보를 하나의 플랫폼에 모으자.

이를 흔히 Single Source of Truth, 즉 단일 진실 공급원이라고 부른다.

이론적으로는 합리적인 접근이다. 하지만 실제 조직에서는 제대로 실현되기 어렵다.

사람들은 정보를 관리하기 좋은 장소보다, 업무를 처리하기 편한 장소에 기록하기 때문이다.

예를 들어 개발팀은 Slack에서 기술적인 결정을 내리고, GitHub Pull Request에서 구현 방향을 토론하며, Jira 이슈에 진행 상태를 남긴다.

이 정보를 모두 특정 지식 관리 플랫폼으로 다시 옮기는 작업은 지속되기 어렵다.

따라서 현실적인 사내 지식 검색 시스템은 모든 사용자의 작성 습관을 바꾸기보다, 기존 도구에 흩어진 정보를 수집하고 검색할 수 있어야 한다.

2.2 Slack 메시지는 일반 문서와 다르다

Slack 데이터는 RAG에서 다루기 까다로운 대표적인 비정형 데이터다.

일반 문서는 하나의 문단이나 페이지에 비교적 완전한 의미가 담겨 있다. 반면 Slack 메시지는 대화의 전후 맥락에 의존한다.

예를 들어 다음과 같은 메시지가 있다고 가정해 보자.

A: 이번 장애 원인이 뭐였나요?

B: 캐시 만료 정책 때문입니다.

C: 확인했습니다.

B: 정확히는 Redis TTL이 배포 과정에서 기본값으로 변경됐습니다.

각 메시지를 개별 청크로 저장하면 문제가 발생한다.

캐시 만료 정책 때문입니다라는 메시지는 질문과 분리될 경우 무엇을 설명하는지 알 수 없다.

확인했습니다와 같은 짧은 메시지는 검색 가치가 거의 없지만, 임베딩 유사도에 따라 검색 결과 상단에 나타날 수 있다.

또한 가장 중요한 기술적 설명이 스레드 중간이나 마지막에 위치할 수도 있다.

즉, Slack 데이터를 메시지 단위로 단순 벡터화하면 다음과 같은 문제가 발생한다.

전후 맥락 손실
짧은 메시지의 과도한 노출
검색 가치가 낮은 응답 포함
중요한 장문 설명 누락
질문과 답변 관계 분리

Cerebras는 이를 해결하기 위해 Slack 데이터를 검색 전에 가공하는 파이프라인을 구축했다.

3. PostgreSQL 하나로 검색 시스템 구성하기

Cerebras Knowledge에서 가장 눈에 띄는 선택은 전용 벡터 데이터베이스를 사용하지 않았다는 점이다.

제공된 기사에 따르면 검색 인프라는 PostgreSQL을 중심으로 구성되어 있다.

키워드 검색: PostgreSQL Full Text Search와 GIN 인덱스
벡터 검색: pgvector
벡터 인덱스: HNSW
구조화 데이터 및 메타데이터: 일반 PostgreSQL 컬럼
원문 데이터: 동일 데이터베이스에 저장

일반적인 RAG 서비스에서는 다음과 같이 여러 저장소를 분리하는 경우가 많다.

PostgreSQL
- 사용자
- 권한
- 문서 메타데이터

Vector DB
- 임베딩
- 벡터 검색

Elasticsearch
- 키워드 검색
- 로그 검색

반면 Cerebras 방식은 이를 하나의 PostgreSQL 시스템으로 단순화한다.

PostgreSQL
- 원문
- 정규화된 문서
- 임베딩
- 키워드 인덱스
- 메타데이터
- 시간 정보
- 데이터 출처

3.1 PostgreSQL 중심 설계의 장점

운영 복잡도 감소

데이터베이스 종류가 늘어나면 배포, 백업, 모니터링, 장애 대응 체계도 복잡해진다.

PostgreSQL 하나를 사용하면 다음 항목을 일관되게 관리할 수 있다.

백업
복구
마이그레이션
트랜잭션
접근 권한
모니터링
데이터 정합성

데이터 동기화가 단순하다

문서 원문은 PostgreSQL에 있고 임베딩은 별도 벡터 DB에 저장되어 있다면, 문서 수정 시 두 시스템을 모두 갱신해야 한다.

이때 다음과 같은 오류가 발생할 수 있다.

원문은 최신인데 벡터는 이전 버전인 상태
삭제된 문서의 벡터가 남아 있는 상태
문서는 존재하지만 임베딩 생성에 실패한 상태
재처리 중 중복 벡터가 생성된 상태

동일 데이터베이스에 원문과 임베딩을 저장하면 이러한 동기화 문제를 줄일 수 있다.

개발자의 학습 비용이 낮다

PostgreSQL은 대부분의 백엔드 엔지니어가 사용 경험을 가지고 있다.

새로운 벡터 데이터베이스의 쿼리 문법, 운영 방식, 백업 정책, 클러스터 구조를 추가로 학습하지 않아도 된다는 장점이 있다.

3.2 PostgreSQL만으로 충분한가?

모든 RAG 시스템에 PostgreSQL이 적합한 것은 아니다.

다음과 같은 상황에서는 전용 검색 시스템이 더 적절할 수 있다.

수억 개 이상의 임베딩을 검색해야 하는 경우
초당 검색 요청이 매우 높은 경우
복잡한 언어별 형태소 분석이 필요한 경우
여러 지역에 걸친 분산 검색이 필요한 경우
벡터 인덱스를 독립적으로 확장해야 하는 경우
고급 필터링과 랭킹 기능이 필요한 경우

그러나 사내 지식 검색처럼 데이터 규모가 통제 가능하고, 메타데이터 필터링과 정합성이 중요한 환경에서는 PostgreSQL이 실용적인 선택이 될 수 있다.

핵심은 “전용 벡터 DB가 항상 필요하다”가 아니라, 시스템 규모와 운영 조건에 따라 저장소를 선택해야 한다는 점이다.

4. Slack 스레드를 검색 가능한 문서로 변환하기

Cerebras는 Slack 메시지를 그대로 임베딩하지 않는다.

먼저 스레드 전체를 LLM에 입력하고, 검색에 적합한 구조화 문서로 변환한다.

개념적으로는 다음과 같은 처리 과정이다.

Slack 원본 스레드
        ↓
대화 분석
        ↓
핵심 주제 추출
        ↓
질문과 답변 관계 복원
        ↓
기술적 결론 요약
        ↓
예상 검색 질문 생성
        ↓
정규화 문서 저장
        ↓
임베딩 생성

예를 들어 원본 Slack 스레드가 다음과 같다고 하자.

A: 배포 이후 API 응답이 느려진 이유가 뭔가요?

B: DB 문제는 아닌 것 같습니다.

C: 로그를 보니 캐시 적중률이 20%대로 내려갔습니다.

B: 배포 스크립트에서 Redis TTL 환경 변수가 누락됐네요.

A: 기본값이 적용된 건가요?

B: 네. 수정 후 캐시 적중률이 정상화됐습니다.

이를 검색용 문서로 변환하면 다음과 같이 정리할 수 있다.

제목:
배포 이후 API 응답 지연과 Redis TTL 환경 변수 누락

요약:
배포 스크립트에서 Redis TTL 환경 변수가 누락되면서
기본 만료 시간이 적용되었고, 캐시 적중률이 약 20%대로 감소했다.
환경 변수를 복원한 후 캐시 적중률과 API 응답 속도가 정상화되었다.

예상 검색 질문:
- 배포 이후 API 응답이 느려진 이유는 무엇인가?
- Redis 캐시 적중률이 감소한 원인은 무엇인가?
- TTL 환경 변수 누락으로 발생한 장애 사례가 있는가?

관련 키워드:
Redis, TTL, 캐시 적중률, 배포 스크립트, API 지연

이렇게 변환하면 사용자가 원문의 정확한 표현을 기억하지 못하더라도 관련 내용을 찾기 쉬워진다.

4.1 예상 질문을 생성하는 이유

임베딩 검색은 질문과 문서가 의미적으로 유사할수록 잘 동작한다.

하지만 원본 문서는 사실을 설명하는 서술형 문장이고, 사용자는 의문형으로 검색하는 경우가 많다.

예를 들어 문서에는 다음과 같이 기록되어 있을 수 있다.

Redis TTL 환경 변수가 누락되어 기본값이 적용됐다.

사용자는 다음과 같이 질문할 수 있다.

지난번 배포 후 API가 느려진 이유가 뭐였지?

두 문장은 동일한 사건을 가리키지만 사용하는 단어와 문장 구조가 다르다.

검색용 예상 질문을 미리 생성하면 사용자 질문과 임베딩 공간에서 가까운 표현을 확보할 수 있다.

이는 흔히 다음과 같은 이름으로 불린다.

Question Generation
Hypothetical Question Indexing
Query-oriented Chunk Enrichment
Document Expansion

4.2 원문도 별도로 보존한다

정규화된 요약만 저장하면 LLM이 생략한 세부 정보가 손실될 수 있다.

따라서 원본 Slack 텍스트도 함께 저장해야 한다.

권장 구조는 다음과 같다.

knowledge_chunks
├── source_type
├── source_id
├── thread_id
├── raw_content
├── normalized_content
├── summary
├── hypothetical_questions
├── keywords
├── embedding
├── author_ids
├── channel_id
├── created_at
├── updated_at
└── metadata

검색 단계에서는 정규화된 문서와 예상 질문을 벡터 검색에 활용하고, 원문은 키워드 검색과 최종 근거 제공에 활용할 수 있다.

5. 긴 Slack 스레드를 처리하는 방법

스레드 전체를 하나의 청크로 만드는 방법도 완전하지 않다.

스레드가 지나치게 길면 중간에 있는 중요한 정보가 임베딩에서 희석될 수 있기 때문이다.

예를 들어 하나의 스레드에 다음 내용이 모두 포함되어 있을 수 있다.

장애 발생 보고
원인 분석
임시 대응
코드 수정
재발 방지 대책
배포 결과
후속 작업

이 스레드를 하나의 벡터로 표현하면 개별 주제의 의미가 약해질 수 있다.

Cerebras는 긴 스레드에서 특정 조건을 충족하는 연속 발언을 별도 청크로 분리하는 방식을 사용한 것으로 소개된다.

특히 한 사용자가 연속해서 작성한 장문의 기술 설명은 독립적인 지식 단위일 가능성이 높다.

개념적인 분할 기준은 다음과 같이 설계할 수 있다.

동일 작성자의 연속 메시지
일정 글자 수 이상의 메시지 묶음
코드 블록을 포함한 설명
URL이나 문서 링크를 포함한 설명
특정 기술 용어가 반복되는 구간
질문에 대한 직접적인 원인 또는 해결책
최종 결정이나 합의를 나타내는 문장

이를 기반으로 스레드에서 여러 종류의 청크를 만들 수 있다.

Slack Thread
├── 스레드 전체 요약 청크
├── 원인 분석 청크
├── 기술 설명 청크
├── 해결 방법 청크
└── 최종 결정 청크

이 구조는 한 가지 청킹 방식만 사용하는 것보다 검색 recall을 높이는 데 유리하다.

6. 검색할 때 네 가지 신호를 함께 사용한다

Cerebras Knowledge는 사용자의 질문이 들어왔을 때 하나의 검색 방식만 사용하지 않는다.

서로 다른 검색 신호를 병렬로 계산한 후 결과를 결합한다.

기사에서 소개된 주요 신호는 다음 네 가지다.

키워드 검색
벡터 검색
IDF 기반 희귀 단어 가중치
정보 신선도

6.1 키워드 검색

키워드 검색은 사용자가 입력한 단어가 문서에 직접 포함되어 있는지를 확인한다.

예를 들어 다음과 같은 검색에 강하다.

정확한 클래스 이름
오류 코드
티켓 번호
프로젝트 이름
사람 이름
API 엔드포인트
라이브러리 이름
커밋 해시

ERR_CONNECTION_RESET
JIRA-1842
payment-webhook
RedisClusterManager

이런 값은 의미 기반 임베딩보다 정확한 문자열 매칭이 중요하다.

PostgreSQL에서는 tsvector, tsquery, GIN 인덱스를 사용해 전체 텍스트 검색을 구현할 수 있다.

개념적인 SQL은 다음과 같다.

SELECT
    id,
    normalized_content,
    ts_rank(search_vector, query) AS keyword_score
FROM knowledge_chunks,
     plainto_tsquery('simple', :query) AS query
WHERE search_vector @@ query
ORDER BY keyword_score DESC
LIMIT 50;

6.2 벡터 검색

벡터 검색은 표현이 다르더라도 의미가 비슷한 문서를 찾는 데 사용된다.

예를 들어 사용자가 다음과 같이 질문한다고 하자.

서비스 배포 후 갑자기 느려졌던 사건

문서에는 다음 표현만 존재할 수 있다.

릴리스 이후 캐시 적중률 저하로 API latency가 증가했다.

정확히 일치하는 단어는 적지만 의미는 유사하다.

pgvector를 사용하면 다음과 같은 형태로 검색할 수 있다.

SELECT
    id,
    normalized_content,
    1 - (embedding <=> :query_embedding) AS vector_score
FROM knowledge_chunks
ORDER BY embedding <=> :query_embedding
LIMIT 50;

6.3 IDF 기반 희귀 단어 가중치

IDF는 Inverse Document Frequency, 즉 역문서 빈도다.

많은 문서에 반복해서 등장하는 단어는 검색 가치가 낮고, 일부 문서에만 등장하는 희귀 단어는 검색 가치가 높다고 판단한다.

예를 들어 Slack에는 다음과 같은 표현이 매우 자주 나타난다.

확인했습니다
감사합니다
알겠습니다
가능합니다
좋습니다
진행하겠습니다

이런 단어가 포함된 메시지는 검색 결과에서 높은 우선순위를 받을 필요가 없다.

반면 다음 표현은 특정 문제와 직접 연결될 가능성이 높다.

NCCL timeout
HNSW index
memory fragmentation
TTL override
compiler regression

IDF 신호를 사용하면 검색 가치가 낮은 상투적 표현을 억제하고, 기술적으로 구체적인 문장을 우대할 수 있다.

6.4 정보 신선도

사내 지식은 시간이 지나면서 변경된다.

6개월 전의 배포 절차보다 지난주에 개정된 배포 절차가 더 정확할 가능성이 높다.

따라서 검색 결과에 시간 가중치를 적용할 수 있다.

예를 들어 다음과 같은 감쇠 함수를 사용할 수 있다.

freshness_score = exp(-λ × document_age)

여기서 document_age는 문서 생성 또는 갱신 후 경과 시간이며, λ는 오래된 정보의 점수를 얼마나 빠르게 낮출지를 결정한다.

다만 최신 문서가 항상 정답인 것은 아니다.

오래된 장애 회고, 기술적 결정 기록, 설계 배경은 시간이 지나도 가치가 유지될 수 있다.

따라서 데이터 유형에 따라 신선도 가중치를 다르게 적용하는 것이 안전하다.

운영 절차       → 신선도 가중치 높음
현재 담당자 정보 → 신선도 가중치 높음
장애 회고       → 신선도 가중치 중간
아키텍처 결정   → 신선도 가중치 중간
역사적 기록     → 신선도 가중치 낮음

7. RRF로 검색 결과를 통합한다

키워드 검색과 벡터 검색은 각각 다른 점수 체계를 사용한다.

예를 들어 키워드 검색 점수는 0.72, 벡터 유사도는 0.84, 신선도 점수는 0.56처럼 계산될 수 있다.

이 점수들을 단순히 더하면 각 점수의 범위와 분포가 달라 결과가 왜곡될 수 있다.

Cerebras는 여러 랭킹을 결합하기 위해 RRF, Reciprocal Rank Fusion을 사용하는 것으로 소개된다.

RRF는 검색 결과의 절대 점수보다 각 검색 방식에서 몇 위에 올랐는지를 사용한다.

기본적인 식은 다음과 같다.

RRF Score(d) = Σ 1 / (k + rankᵢ(d))

d: 문서
rankᵢ(d): i번째 검색 방식에서 해당 문서의 순위
k: 상위 결과의 점수 차이를 완화하는 상수

예를 들어 어떤 문서가 다음 순위를 기록했다고 하자.

키워드 검색: 2위
벡터 검색: 5위
신선도 랭킹: 3위

k = 60이면 다음과 같이 계산할 수 있다.

RRF = 1 / 62 + 1 / 65 + 1 / 63

RRF의 장점은 다음과 같다.

검색 점수 정규화가 필요하지 않다.
서로 다른 검색 엔진의 결과를 쉽게 결합할 수 있다.
특정 검색 방식 하나에 과도하게 의존하지 않는다.
구현이 단순하다.
하이브리드 검색의 안정성이 높다.

8. 소형 리랭커로 최종 문서를 선별한다

RRF로 검색 결과를 합친 뒤에도 상위 문서가 모두 질문에 적합한 것은 아니다.

따라서 상위 후보에 대해 리랭커를 적용한다.

일반적인 검색 파이프라인은 다음과 같다.

사용자 질문
    ↓
키워드 검색 Top 50
벡터 검색 Top 50
IDF 랭킹 Top 50
신선도 랭킹 Top 50
    ↓
RRF 통합
    ↓
상위 30~50개 후보
    ↓
소형 리랭커
    ↓
최종 Top 10
    ↓
LLM 컨텍스트 구성

리랭커는 질문과 각 문서를 함께 입력받아 관련성을 직접 판단한다.

벡터 검색이 질문과 문서를 각각 독립적으로 임베딩하는 bi-encoder 방식이라면, 리랭커는 질문과 문서를 동시에 비교하는 cross-encoder 방식으로 구현되는 경우가 많다.

리랭커는 일반적으로 벡터 검색보다 정확하지만 계산 비용이 높다.

따라서 전체 문서를 리랭킹하지 않고, 1차 검색으로 좁힌 후보에만 적용한다.

9. 검색된 청크에 주변 문맥을 다시 붙인다

검색용 청크는 정확한 검색을 위해 작게 분할해야 한다.

그러나 LLM에 제공하는 컨텍스트는 충분한 문맥을 포함해야 한다.

이 때문에 검색에 사용한 청크와 생성 모델에 제공하는 청크를 동일하게 구성할 필요는 없다.

예를 들어 검색 결과가 Slack 스레드 중간의 기술 설명이라면, 최종적으로 LLM에 전달할 때는 다음 내용을 추가할 수 있다.

최초 질문
검색된 핵심 메시지
바로 앞 메시지
바로 뒤 메시지
스레드 최종 결론
연결된 문서나 코드 링크
작성자와 작성 시점

이를 context expansion, neighbor expansion, parent-child retrieval 등의 방식으로 구현할 수 있다.

작은 청크로 검색
        ↓
관련 청크 선택
        ↓
부모 문서 또는 주변 청크 로드
        ↓
확장된 컨텍스트를 LLM에 전달

이 방식은 검색 정확도와 답변 완성도를 동시에 확보하는 데 유리하다.

10. MCP에는 완성형 답변이 아니라 검색 도구를 공개한다

Cerebras Knowledge는 인간이 사용하는 웹 인터페이스뿐 아니라 AI 에이전트가 호출할 수 있는 MCP 인터페이스도 제공한다.

여기서 중요한 설계 원칙은 AI 에이전트에게 다음과 같은 단일 도구를 제공하지 않는다는 점이다.

answer_company_question(question)

대신 보다 작은 검색 도구를 제공한다.

search_slack(query)
search_code(query)
search_documents(query)
search_jira(query)

이러한 도구를 흔히 primitive tool, 즉 기본 단위 도구라고 부를 수 있다.

AI 에이전트는 사용자의 요청을 분석하고 필요한 도구를 스스로 선택한다.

예를 들어 다음 질문이 들어왔다고 하자.

결제 웹훅 중복 처리 문제가 왜 발생했고 현재 코드는 어떻게 수정됐나요?

에이전트는 다음과 같은 순서로 동작할 수 있다.

1. search_slack
   - 장애 당시 논의와 원인 검색

2. search_jira
   - 관련 이슈와 후속 작업 검색

3. search_code
   - 현재 구현 코드와 커밋 검색

4. 결과 비교
   - 과거 원인과 현재 수정 상태를 연결

5. 최종 답변 생성

검색 시스템이 모든 질문을 한 번에 해결하려 하기보다, 에이전트가 조합할 수 있는 작은 기능을 제공하는 구조다.

10.1 인간용 인터페이스와 AI용 인터페이스의 차이

인간 사용자는 일반적으로 다음과 같은 경험을 원한다.

질문 입력
답변 확인
근거 문서 열기
추가 질문
검색 결과 필터링

반면 AI 에이전트는 다음을 필요로 한다.

구조화된 입력과 출력
데이터 출처 구분
검색 범위 지정
페이지네이션
메타데이터 필터
재현 가능한 결과
근거 식별자
원문 조회 기능

따라서 인간용 챗봇 API와 AI 에이전트용 검색 API를 분리하는 것은 합리적인 접근이다.

11. 전체 아키텍처 예시

Cerebras 사례를 참고해 사내 지식 검색 시스템을 구성하면 다음과 같은 구조를 설계할 수 있다.

┌─────────────────────────────────────┐
│            데이터 소스              │
│ Slack · GitHub · Jira · Drive       │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│          수집 및 동기화 계층         │
│ Webhook · Polling · Incremental Sync│
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│          전처리 파이프라인           │
│ 정규화 · 중복 제거 · 권한 추출      │
│ 스레드 요약 · 질문 생성 · 청크 분할 │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│             PostgreSQL              │
│ 원문 · 요약 · 메타데이터 · 임베딩   │
│ Full Text Search · pgvector · HNSW │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│             검색 계층               │
│ Keyword · Vector · IDF · Freshness │
│ RRF · Reranker · Context Expansion │
└──────────────────┬──────────────────┘
                   │
          ┌────────┴────────┐
          ▼                 ▼
┌─────────────────┐ ┌─────────────────┐
│   인간용 Web UI  │ │ AI Agent · MCP  │
│ 검색 · 채팅      │ │ search_slack    │
│ 출처 · 피드백    │ │ search_code     │
└─────────────────┘ └─────────────────┘

12. 실제 구현 시 가장 어려운 문제: 권한 관리

기사에서도 한계로 지적된 부분이 권한 관리다.

사내 데이터는 모든 직원에게 동일하게 공개되지 않는다.

예를 들어 다음과 같은 접근 제한이 존재할 수 있다.

비공개 Slack 채널
경영진 전용 문서
인사 평가 자료
법무 관련 문서
특정 프로젝트 참여자 전용 GitHub 저장소
고객 계약 자료
보안 사고 보고서

원본 서비스의 검색 API를 직접 사용하는 경우에는 해당 서비스의 권한 체계를 활용할 수 있다.

예를 들어 사용자의 Slack 토큰으로 Slack 검색 API를 호출하면, 사용자가 접근 가능한 채널만 검색된다.

하지만 데이터를 별도 PostgreSQL에 복제하면 권한 모델도 함께 복제해야 한다.

원본 데이터 복제
      +
권한 정보 복제
      +
사용자 그룹 동기화
      +
검색 시 권한 필터링

이 중 하나라도 누락되면 민감한 정보가 노출될 수 있다.

12.1 권한 필터링 기본 구조

각 지식 청크에 접근 제어 정보를 저장할 수 있다.

knowledge_chunks
├── allowed_user_ids
├── allowed_group_ids
├── source_channel_id
├── source_repository_id
├── visibility
└── classification_level

검색할 때는 벡터 유사도 계산만 수행하는 것이 아니라, 현재 사용자의 권한 조건을 함께 적용해야 한다.

SELECT
    id,
    normalized_content,
    1 - (embedding <=> :query_embedding) AS score
FROM knowledge_chunks
WHERE
    visibility = 'public'
    OR :user_id = ANY(allowed_user_ids)
    OR allowed_group_ids && :user_group_ids
ORDER BY embedding <=> :query_embedding
LIMIT 20;

중요한 점은 검색 후 결과를 제거하는 것이 아니라, 검색 단계부터 권한 조건을 적용해야 한다는 것이다.

검색 후 필터링 방식은 다음과 같은 문제를 일으킬 수 있다.

권한 없는 문서가 상위 결과를 차지함
권한 필터링 후 결과가 부족함
검색 점수나 로그를 통해 정보가 간접 노출됨
리랭커나 LLM에 민감한 문서가 전달될 가능성

12.2 삭제와 권한 변경도 동기화해야 한다

데이터 수집보다 더 어려운 것은 삭제와 권한 변경이다.

예를 들어 다음 상황을 처리해야 한다.

공개 채널이 비공개 채널로 변경됨
사용자가 프로젝트에서 제외됨
GitHub 저장소 접근 권한이 제거됨
문서가 삭제됨
Slack 메시지가 수정됨
민감 정보가 포함되어 원문이 삭제됨

RAG 시스템에 이전 데이터가 남아 있다면 원본에서 권한이 제거되더라도 계속 검색될 수 있다.

따라서 동기화 시스템은 생성 이벤트뿐 아니라 다음 이벤트를 추적해야 한다.

Create
Update
Delete
Permission Change
Membership Change
Visibility Change

13. 하나의 거대한 지식 기반은 계속 유지될 수 있을까?

초기에는 모든 데이터를 하나의 지식 기반에 저장하는 방식이 단순하고 효율적일 수 있다.

그러나 데이터와 사용 사례가 증가하면 하나의 검색 랭킹으로 모든 질문을 처리하기 어려워질 수 있다.

예를 들어 다음 질문은 서로 다른 검색 전략이 필요하다.

코드 오류 원인을 찾아줘.

지난 분기 영업 전략을 알려줘.

휴가 신청 절차가 어떻게 되나요?

고객 A와 체결한 계약 조건을 찾아줘.

코드 검색은 함수명, 경로, 심볼, 커밋 관계가 중요하다.

인사 규정 검색은 최신 공식 문서와 정확한 조항이 중요하다.

영업 자료 검색은 고객, 산업, 시점, 담당 조직이 중요하다.

따라서 시스템이 성장하면 도메인별 검색 구성이 필요할 수 있다.

Engineering Knowledge
- GitHub
- Jira
- 기술 Slack
- 설계 문서

Sales Knowledge
- CRM
- 제안서
- 고객 미팅 기록
- 영업 Slack

HR Knowledge
- 사내 규정
- 복지 문서
- 인사 공지

Legal Knowledge
- 계약서
- 정책
- 컴플라이언스 문서

이때 상위 에이전트가 질문을 분류한 후 적절한 검색 도구를 선택하도록 구성할 수 있다.

사용자 질문
      ↓
도메인 라우터
      ↓
Engineering / Sales / HR / Legal
      ↓
도메인별 검색
      ↓
통합 답변

다만 도메인을 분리할수록 권한 관리와 운영 복잡도는 증가한다.

따라서 처음부터 과도하게 분리하기보다, 검색 품질과 데이터 규모를 관찰하면서 단계적으로 분리하는 것이 현실적이다.

14. 실무에 적용할 수 있는 핵심 교훈

14.1 벡터 데이터베이스부터 선택하지 않는다

RAG 시스템을 구축할 때 기술 스택부터 결정하는 경우가 많다.

Pinecone을 사용할까?
Weaviate를 사용할까?
Milvus를 사용할까?
Elasticsearch를 사용할까?

그러나 검색 품질을 결정하는 핵심은 데이터베이스 제품보다 다음 요소일 가능성이 높다.

원본 데이터의 품질
청크 분할 방식
메타데이터 설계
질문과 문서의 표현 차이
권한 필터링
최신 정보 반영
검색 결과 결합
리랭킹
근거 문맥 확장

소규모 또는 중간 규모의 사내 지식 시스템이라면 PostgreSQL과 pgvector로 먼저 검증하는 접근도 가능하다.

14.2 채팅 데이터는 반드시 대화 단위로 처리한다

Slack이나 Teams 메시지를 개별 메시지 단위로 임베딩하는 방식은 피하는 것이 좋다.

최소한 다음 처리가 필요하다.

스레드 단위 병합
질문과 답변 관계 복원
짧은 응답 제거
장문 설명 별도 추출
결론과 결정 사항 요약
예상 검색 질문 생성
원문과 정규화 문서 병행 저장

14.3 검색은 하나의 방식으로 해결하지 않는다

벡터 검색만으로는 다음 항목을 정확히 찾기 어렵다.

오류 코드
프로젝트명
함수명
티켓 번호
파일 경로
사람 이름
버전 번호

반대로 키워드 검색만으로는 표현이 다른 질문을 찾기 어렵다.

따라서 실무에서는 하이브리드 검색이 필요하다.

Keyword
+ Vector
+ Metadata
+ Freshness
+ RRF
+ Reranker

14.4 검색용 청크와 답변용 컨텍스트를 분리한다

검색에는 작은 청크가 유리하지만, 답변에는 충분한 문맥이 필요하다.

따라서 다음 구조가 효과적이다.

작은 청크로 검색
→ 부모 문서 확인
→ 주변 문맥 확장
→ 최종 컨텍스트 구성

14.5 AI 에이전트에는 작고 명확한 도구를 제공한다

MCP 도구는 하나의 거대한 답변 API보다 기능별 검색 도구로 제공하는 것이 활용성이 높다.

search_slack
search_code
search_jira
fetch_document
get_thread
get_commit

AI 에이전트가 목적에 맞게 도구를 조합할 수 있기 때문이다.

14.6 권한 관리는 나중에 추가할 기능이 아니다

기업용 RAG에서 권한 관리는 부가 기능이 아니라 핵심 아키텍처다.

데이터 모델을 설계할 때부터 다음 항목이 포함되어야 한다.

사용자 ID
그룹 ID
조직 ID
원본 서비스 권한
문서 공개 범위
검색 시 ACL 필터
권한 변경 동기화
삭제 전파
검색 및 열람 감사 로그

15. 단계별 구축 전략

Cerebras 사례를 참고하되 처음부터 모든 기능을 구현할 필요는 없다.

다음과 같이 단계적으로 구축할 수 있다.

1단계: 기본 검색 MVP

PostgreSQL
pgvector
문서 수집
기본 청킹
벡터 검색
출처 표시

2단계: 하이브리드 검색

PostgreSQL Full Text Search
키워드와 벡터 검색 병렬 실행
RRF 통합
메타데이터 필터

3단계: Slack 최적화

스레드 단위 수집
LLM 요약
예상 질문 생성
장문 메시지 별도 청킹
원문 보존

4단계: 검색 품질 향상

리랭커
신선도 점수
IDF 기반 노이즈 억제
컨텍스트 확장
사용자 피드백 수집

5단계: 엔터프라이즈 권한

사용자 및 그룹 동기화
문서 ACL 저장
검색 단계 권한 필터링
삭제와 권한 변경 동기화
감사 로그

6단계: AI 에이전트 연동

MCP 서버
search_slack
search_code
search_documents
원문 조회 도구
도메인별 검색 라우팅

16. 결론

Cerebras의 사내 지식 검색 사례에서 가장 중요한 점은 특정한 벡터 데이터베이스나 최신 AI 모델을 사용했다는 것이 아니다.

오히려 다음과 같은 기본 원칙을 충실히 적용했다는 점이 중요하다.

데이터를 작성되는 장소에서 수집한다.
Slack 대화를 검색 가능한 문서로 정규화한다.
키워드 검색과 벡터 검색을 함께 사용한다.
희귀 단어와 최신 정보를 랭킹에 반영한다.
RRF로 여러 검색 결과를 결합한다.
소형 리랭커로 최종 관련성을 평가한다.
검색 후 주변 문맥을 다시 확장한다.
인간용 인터페이스와 AI 에이전트용 도구를 구분한다.
운영 복잡도를 낮추기 위해 PostgreSQL을 중심으로 구성한다.

이 사례는 RAG 시스템의 성능이 단순히 임베딩 모델이나 벡터 데이터베이스 성능으로 결정되지 않는다는 사실을 보여준다.

좋은 사내 지식 시스템을 만들기 위해서는 검색 기술뿐 아니라 데이터 전처리, 동기화, 권한 관리, 사용자 경험, 에이전트 인터페이스를 하나의 시스템으로 설계해야 한다.

특히 초기 단계에서는 복잡한 분산 아키텍처보다 다음과 같은 단순한 구성으로 시작하는 것이 현실적일 수 있다.

PostgreSQL
+ pgvector
+ Full Text Search
+ RRF
+ Reranker
+ 권한 필터

그 위에 Slack 정규화, 코드 검색, MCP, 도메인 라우팅을 단계적으로 추가하면 운영 가능한 엔터프라이즈 지식 기반으로 발전시킬 수 있다.

참고 개념

Retrieval-Augmented Generation, RAG
PostgreSQL Full Text Search
GIN Index
pgvector
HNSW
Inverse Document Frequency, IDF
Reciprocal Rank Fusion, RRF
Cross-Encoder Reranker
Hypothetical Question Generation
Context Expansion
Model Context Protocol, MCP
Access Control List, ACL

# 한눈에 정리하는 23가지 핵심 디자인 패턴 (Design Patterns for Humans)

행복한 수지아빠 — Wed, 5 Aug 2026 14:41:11 +0900

"디자인 패턴을 머릿속에 쏙쏙 들어오게!"
누구나 한번쯤 머리가 아팠을 디자인 패턴, 직관적인 현실 세계 비유와 JavaScript(Node.js) & Python 예제 코드로 가장 쉽고 명쾌하게 정리했습니다.

목차 (Table of Contents)

️ 생성 패턴 (Creational)	구조 패턴 (Structural)	행동 패턴 (Behavioral)
Simple Factory	Adapter	Chain of Responsibility
Factory Method	Bridge	Command
Abstract Factory	Composite	➿ Iterator
Builder	☕ Decorator	Mediator
Prototype	Facade	Memento
Singleton	Flyweight	Observer
	Proxy	Visitor
		Strategy
		State
		Template Method

디자인 패턴 들어가기 (Introduction)

[!IMPORTANT]
디자인 패턴이란?
자주 발생하는 문제들에 대한 일반적이고 재사용 가능한 해결책(가이드라인)입니다. 가져다 바로 꽂아 넣는 플러그인이나 라이브러리가 아니라, 상황을 풀어나가기 위한 디자인 템플릿에 가깝습니다.

⚠️ 사용 시 주의사항 (Be Careful)

만능 해결책(Silver Bullet)이 아닙니다. 패턴을 억지로 적용하려고 하면 오히려 설계가 어그러집니다.
문제에 맞춘 해결책입니다. 해결책에 맞춰 문제를 발굴하는 과도한 설계를 경계하세요.
적재적소에 올바르게 쓰면 훌륭한 구원자가 되지만, 잘못 남용하면 코드가 악몽의 난장판이 될 수 있습니다.

️ 생성 디자인 패턴 (Creational Design Patterns)

한 줄 요약: 객체 또는 연관된 객체 그룹을 어떻게 인스턴스화할 것인가에 집중하는 패턴입니다.

1. Simple Factory (쉬운 공장)

현실 예시:
집을 짓다가 문이 필요할 때 직접 목수 옷을 입고 나무와 톱을 들고 문을 짤 수도 있지만, 공장에 주문해서 배송받는 편이 훨씬 깔끔합니다. 문을 만드는 복잡한 과정이나 먼지를 뒤집어쓸 필요가 없기 때문입니다.

한 줄 정의:
클라이언트에게 인스턴스화 로직을 노출하지 않고 인스턴스를 만들어 제공합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class WoodenDoor {
  constructor(width, height) {
    this.width = width;
    this.height = height;
  }

  getWidth() {
    return this.width;
  }

  getHeight() {
    return this.height;
  }
}

class DoorFactory {
  static makeDoor(width, height) {
    return new WoodenDoor(width, height);
  }
}

// 사용 예시
const door = DoorFactory.makeDoor(100, 200);
console.log(`Width: ${door.getWidth()}, Height: ${door.getHeight()}`);

Python 예제 보기

from abc import ABC, abstractmethod

class Door(ABC):
    @abstractmethod
    def get_width(self) -> float: pass

    @abstractmethod
    def get_height(self) -> float: pass

class WoodenDoor(Door):
    def __init__(self, width: float, height: float):
        self._width = width
        self._height = height

    def get_width(self) -> float: return self._width
    def get_height(self) -> float: return self._height

class DoorFactory:
    @staticmethod
    def make_door(width: float, height: float) -> Door:
        return WoodenDoor(width, height)

# 사용 예시
door1 = DoorFactory.make_door(100, 200)
print(f"Width: {door1.get_width()}, Height: {door1.get_height()}")

언제 사용하나요?
단순 생성을 넘어 약간의 초기화 로직이나 설정 작업이 필요할 때, 해당 생성을 전용 팩토리 클래스로 묶어 코드 중복을 방지할 때 사용합니다.

2. Factory Method (공장 메서드)

현실 예시:
총괄 채용 매니저 혼자 모든 직군의 면접을 진행하는 것은 불가능합니다. 면접 진행이라는 전체 큰 틀은 갖고 있되, 구체적으로 어떤 면접관을 세울지는 각 분야(개발, 마케팅) 팀장에게 위임합니다.

한 줄 정의:
객체 생성 인터페이스를 정의하지만, 어떤 클래스의 인스턴스를 생성할지는 서브클래스에 위임합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Developer {
  askQuestions() {
    console.log('디자인 패턴에 대해 질문합니다!');
  }
}

class CommunityExecutive {
  askQuestions() {
    console.log('커뮤니티 빌딩에 대해 질문합니다!');
  }
}

class HiringManager {
  // Factory Method (하위 클래스에서 구현)
  makeInterviewer() {
    throw new Error('makeInterviewer() 메서드를 구현해야 합니다.');
  }

  takeInterview() {
    const interviewer = this.makeInterviewer();
    interviewer.askQuestions();
  }
}

class DevelopmentManager extends HiringManager {
  makeInterviewer() {
    return new Developer();
  }
}

class MarketingManager extends HiringManager {
  makeInterviewer() {
    return new CommunityExecutive();
  }
}

// 사용 예시
const devManager = new DevelopmentManager();
devManager.takeInterview(); // 디자인 패턴에 대해 질문합니다!

const marketingManager = new MarketingManager();
marketingManager.takeInterview(); // 커뮤니티 빌딩에 대해 질문합니다!

Python 예제 보기

from abc import ABC, abstractmethod

class Interviewer(ABC):
    @abstractmethod
    def ask_questions(self): pass

class Developer(Interviewer):
    def ask_questions(self):
        print("디자인 패턴에 대해 질문합니다!")

class CommunityExecutive(Interviewer):
    def ask_questions(self):
        print("커뮤니티 빌딩에 대해 질문합니다!")

class HiringManager(ABC):
    @abstractmethod
    def make_interviewer(self) -> Interviewer: pass

    def take_interview(self):
        interviewer = self.make_interviewer()
        interviewer.ask_questions()

class DevelopmentManager(HiringManager):
    def make_interviewer(self) -> Interviewer:
        return Developer()

# 사용 예시
dev_manager = DevelopmentManager()
dev_manager.take_interview()

언제 사용하나요?
상위 클래스가 자신이 생성해야 하는 객체의 구체적인 클래스를 미리 알 수 없을 때 유용합니다.

3. Abstract Factory (추상 공장)

현실 예시:
목재 문에는 목수가 필요하고, 철제 문에는 용접공이 필요합니다. 문이라는 제품과 설치 기사라는 전문가 사이에 끈끈한 연관성/의존성이 존재할 때 이를 그룹 단위로 세트로 제공하는 매장 개념입니다.

한 줄 정의:
연관되거나 의존적인 객체들의 패밀리를 구체적인 클래스 지정 없이 생성할 수 있는 "공장들의 공장"입니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class WoodenDoor {
  getDescription() { console.log('목재 문입니다.'); }
}
class IronDoor {
  getDescription() { console.log('철제 문입니다.'); }
}

class Carpenter {
  getDescription() { console.log('목재 문 전문가입니다.'); }
}
class Welder {
  getDescription() { console.log('철제 문 전문가입니다.'); }
}

// 추상 공장 역
class WoodenDoorFactory {
  makeDoor() { return new WoodenDoor(); }
  makeFittingExpert() { return new Carpenter(); }
}

class IronDoorFactory {
  makeDoor() { return new IronDoor(); }
  makeFittingExpert() { return new Welder(); }
}

// 사용 예시
const woodenFactory = new WoodenDoorFactory();
const door = woodenFactory.makeDoor();
const expert = woodenFactory.makeFittingExpert();

door.getDescription();   // 목재 문입니다.
expert.getDescription(); // 목재 문 전문가입니다.

Python 예제 보기

from abc import ABC, abstractmethod

class Door(ABC):
    @abstractmethod
    def get_description(self): pass

class WoodenDoor(Door):
    def get_description(self): print("목재 문입니다.")

class DoorFittingExpert(ABC):
    @abstractmethod
    def get_description(self): pass

class Carpenter(DoorFittingExpert):
    def get_description(self): print("목재 문 전문가입니다.")

class DoorFactory(ABC):
    @abstractmethod
    def make_door(self) -> Door: pass
    @abstractmethod
    def make_fitting_expert(self) -> DoorFittingExpert: pass

class WoodenDoorFactory(DoorFactory):
    def make_door(self) -> Door: return WoodenDoor()
    def make_fitting_expert(self) -> DoorFittingExpert: return Carpenter()

# 사용 예시
factory = WoodenDoorFactory()
door = factory.make_door()
expert = factory.make_fitting_expert()
door.get_description()
expert.get_description()

언제 사용하나요?
연관된 제품군을 묶어서 생성해야 하고, 서로 호환되지 않는 제품들이 섞이는 것을 방지하고 싶을 때 사용합니다.

4. Builder (빌더)

현실 예시:
패스트푸드점에서 "세트 하나 주세요"는 단순 생성(Simple Factory)이지만, 수제 샌드위치 매장에서 "빵은 아티잔, 치즈는 체다, 소스는 칠리 추가해주세요"처럼 복잡한 옵션을 단계별로 조합하는 것이 빌더입니다.

한 줄 정의:
복잡한 객체의 생성 과정과 표현 방법을 분리하여 동일한 생성 절차에서 서로 다른 표현 결과를 만들 수 있게 합니다 (망원경 생성자 안티패턴 방지).

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Burger {
  constructor(builder) {
    this.size = builder.size;
    this.cheese = builder.cheese || false;
    this.pepperoni = builder.pepperoni || false;
    this.lettuce = builder.lettuce || false;
    this.tomato = builder.tomato || false;
  }
}

class BurgerBuilder {
  constructor(size) {
    this.size = size;
  }

  addCheese() {
    this.cheese = true;
    return this;
  }

  addPepperoni() {
    this.pepperoni = true;
    return this;
  }

  addTomato() {
    this.tomato = true;
    return this;
  }

  build() {
    return new Burger(this);
  }
}

// 사용 예시 (메서드 체이닝)
const burger = new BurgerBuilder(14)
  .addPepperoni()
  .addCheese()
  .build();

Python 예제 보기

class Burger:
    def __init__(self, builder):
        self.size = builder.size
        self.cheese = builder.cheese
        self.pepperoni = builder.pepperoni

class BurgerBuilder:
    def __init__(self, size: int):
        self.size = size
        self.cheese = False
        self.pepperoni = False

    def add_cheese(self):
        self.cheese = True
        return self

    def add_pepperoni(self):
        self.pepperoni = True
        return self

    def build(self) -> Burger:
        return Burger(self)

# 사용 예시
burger = BurgerBuilder(14).add_cheese().add_pepperoni().build()

언제 사용하나요?
인자(Parameter)가 엄청 많거나 생성이 여러 단계로 나누어져 선택적 옵션이 많을 때 쓰면 코드가 훨씬 깔끔해집니다.

5. Prototype (프로토타입)

현실 예시:
복제 양 돌리를 생각해 보세요! 처음부터 하나하나 다시 키우고 설계하는 것보다 완성된 원본을 복제(Clone)해서 살짝 수정하는 것이 훨씬 빠르고 비용이 적게 듭니다.

한 줄 정의:
기존 객체를 복제(Cloning)하여 새로운 객체를 생성하는 패턴입니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Sheep {
  constructor(name, category = 'Mountain Sheep') {
    this.name = name;
    this.category = category;
  }

  setName(name) {
    this.name = name;
  }

  getName() {
    return this.name;
  }

  clone() {
    return Object.assign(Object.create(Object.getPrototypeOf(this)), this);
  }
}

// 사용 예시
const original = new Sheep('Jolly');
const cloned = original.clone();
cloned.setName('Dolly');

console.log(original.getName()); // Jolly
console.log(cloned.getName());   // Dolly

Python 예제 보기

import copy

class Sheep:
    def __init__(self, name: str, category: str = "Mountain Sheep"):
        self.name = name
        self.category = category

    def clone(self):
        return copy.deepcopy(self)

# 사용 예시
original = Sheep("Jolly")
cloned = original.clone()
cloned.name = "Dolly"

print(original.name) # Jolly
print(cloned.name)   # Dolly

6. Singleton (싱글톤)

현실 예시:
한 나라에는 한 시점에 오직 단 한 명의 대통령만 존재해야 합니다. 필요할 때마다 대통령을 새로 찍어낼 수는 없습니다.

한 줄 정의:
클래스의 인스턴스가 애플리케이션 내에서 단 하나만 존재하도록 보장하고, 어디서든 접근할 수 있는 전역 접점을 제공합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class President {
  constructor() {
    if (President.instance) {
      return President.instance;
    }
    this.name = 'President';
    President.instance = this;
  }
}

// 사용 예시
const p1 = new President();
const p2 = new President();

console.log(p1 === p2); // true

Python 예제 보기

class President:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

# 사용 예시
p1 = President()
p2 = President()
print(p1 is p2) # True

구조 디자인 패턴 (Structural Design Patterns)

한 줄 요약: 객체들을 큰 구조로 합성하거나, 서로 호환되지 않는 인터페이스를 연결하여 효율적인 관계를 형성하는 것에 관한 패턴입니다.

1. Adapter (어댑터)

현실 예시:
SD 카드의 데이터를 노트북에 옮기고 싶은데 노트북에는 MicroSD 슬롯만 있다면? 카드 리더기(어댑터)를 끼워서 형태를 바꿔 통신합니다.

한 줄 정의:
호환되지 않는 인터페이스를 가진 객체들이 함께 일할 수 있도록 중간에서 변환 역할을 감싸주는(Wrapper) 패턴입니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class AfricanLion {
  roar() {}
}

class Hunter {
  hunt(lion) {
    lion.roar();
  }
}

class WildDog {
  bark() {
    console.log('Woof woof!');
  }
}

// 어댑터 클래스
class WildDogAdapter {
  constructor(dog) {
    this.dog = dog;
  }

  roar() {
    this.dog.bark();
  }
}

// 사용 예시
const dog = new WildDog();
const adapter = new WildDogAdapter(dog);
const hunter = new Hunter();
hunter.hunt(adapter); // Woof woof!

Python 예제 보기

class Lion:
    def roar(self): pass

class Hunter:
    def hunt(self, lion: Lion):
        lion.roar()

class WildDog:
    def bark(self):
        print("Woof woof!")

class WildDogAdapter(Lion):
    def __init__(self, dog: WildDog):
        self.dog = dog

    def roar(self):
        self.dog.bark()

# 사용 예시
dog = WildDog()
adapter = WildDogAdapter(dog)
hunter = Hunter()
hunter.hunt(adapter) # Woof woof!

2. Bridge (브리지)

현실 예시:
웹사이트에 '소개 페이지', '홈 페이지'가 있고 각 페이지는 '다크 테마', '라이트 테마'를 적용할 수 있습니다. 상속으로 만들면 2x2=4개의 클래스를 만들어야 하지만, 페이지(추상화)와 테마(구현)를 브리지로 분리하여 합성하면 클래스가 2+2=4개로 확장성이 훨씬 좋아집니다.

한 줄 정의:
추상화(Abstraction)와 구현(Implementation)을 분리하여 두 계층이 독립적으로 변형될 수 있도록 만드는 패턴입니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class DarkTheme {
  getColor() { return 'Dark Black'; }
}

class LightTheme {
  getColor() { return 'Off White'; }
}

class AboutPage {
  constructor(theme) {
    this.theme = theme;
  }

  getContent() {
    return `About page in ${this.theme.getColor()}`;
  }
}

// 사용 예시
const darkPage = new AboutPage(new DarkTheme());
console.log(darkPage.getContent()); // About page in Dark Black

Python 예제 보기

class DarkTheme:
    def get_color(self): return "Dark Black"

class AboutPage:
    def __init__(self, theme):
        self.theme = theme

    def get_content(self):
        return f"About page in {self.theme.get_color()}"

# 사용 예시
page = AboutPage(DarkTheme())
print(page.get_content())

3. Composite (컴포지트)

현실 예시:
회사는 개별 개발자(단일 객체)들로 구성되기도 하고, 개발팀(객체 그룹)으로 구성되기도 합니다. 대표님이 "이번 달 급여 총액 얼마야?"라고 물었을 때 단일 직원이나 팀 전체나 똑같이 getSalary()로 일관되게 조회할 수 있어야 합니다.

한 줄 정의:
객체들을 트리 구조로 구성하여 개별 객체와 복합 객체를 클라이언트 입장에서 동일하게 다룰 수 있게 합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Developer {
  constructor(name, salary) {
    this.name = name;
    this.salary = salary;
  }

  getSalary() {
    return this.salary;
  }
}

class Organization {
  constructor() {
    this.employees = [];
  }

  addEmployee(employee) {
    this.employees.push(employee);
  }

  getSalary() {
    return this.employees.reduce((total, e) => total + e.getSalary(), 0);
  }
}

// 사용 예시
const org = new Organization();
org.addEmployee(new Developer('John', 1000));
org.addEmployee(new Developer('Jane', 1200));

console.log('Total Salary:', org.getSalary()); // 2200

Python 예제 보기

from abc import ABC, abstractmethod

class Employee(ABC):
    @abstractmethod
    def get_salary(self) -> float: pass

class Developer(Employee):
    def __init__(self, name: str, salary: float):
        self.name = name
        self.salary = salary

    def get_salary(self) -> float: return self.salary

class Organization(Employee):
    def __init__(self):
        self.employees = []

    def add_employee(self, employee: Employee):
        self.employees.append(employee)

    def get_salary(self) -> float:
        return sum(e.get_salary() for e in self.employees)

# 사용 예시
org = Organization()
org.add_employee(Developer("John", 1000))
org.add_employee(Developer("Jane", 1200))
print("Total:", org.get_salary())

☕ 4. Decorator (데코레이터)

현실 예시:
기본 에스프레소 커피에 우유 토핑을 얹으면 라떼가 되고, 휘핑크림을 또 얹으면 모카가 됩니다. 기본 제품의 틀을 변경하지 않고 필요한 옵션을 겉에 겹겹이 포장(감싸서) 추가하는 느낌입니다.

한 줄 정의:
객체에 동적으로 새로운 책임(기능)을 추가하는 패턴으로, 서브클래싱(상속)의 유연한 대안을 제공합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class SimpleCoffee {
  getCost() { return 10; }
  getDescription() { return 'Simple coffee'; }
}

class MilkCoffee {
  constructor(coffee) {
    this.coffee = coffee;
  }

  getCost() {
    return this.coffee.getCost() + 2;
  }

  getDescription() {
    return `${this.coffee.getDescription()}, milk`;
  }
}

// 사용 예시
let coffee = new SimpleCoffee();
coffee = new MilkCoffee(coffee);
console.log(coffee.getCost()); // 12
console.log(coffee.getDescription()); // Simple coffee, milk

Python 예제 보기

class Coffee:
    def get_cost(self) -> float: return 10.0
    def get_description(self) -> str: return "Simple coffee"

class MilkCoffee:
    def __init__(self, coffee: Coffee):
        self._coffee = coffee
    def get_cost(self) -> float: return self._coffee.get_cost() + 2.0
    def get_description(self) -> str: return self._coffee.get_description() + ", milk"

# 사용 예시
coffee = SimpleCoffee()
coffee_with_milk = MilkCoffee(coffee)
print(coffee_with_milk.get_cost()) # 12.0

5. Facade (퍼사드)

현실 예시:
컴퓨터를 켤 때 메인보드 전원 공급, CPU 클럭 가동, 램 전압 체크 등 복잡한 과정을 일일이 조작하지 않습니다. 그저 전원 버튼 하나(Facade)만 누르면 내부 복잡한 서브시스템이 일괄 실행됩니다.

한 줄 정의:
서브시스템의 복잡한 인터페이스 집합에 대해 통합된 단순한 고수준 인터페이스를 제공합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Computer {
  getElectricShock() { console.log('Ouch!'); }
  makeSound() { console.log('Beep beep!'); }
  showLoadingScreen() { console.log('Loading..'); }
}

class ComputerFacade {
  constructor(computer) {
    this.computer = computer;
  }

  turnOn() {
    this.computer.getElectricShock();
    this.computer.makeSound();
    this.computer.showLoadingScreen();
  }
}

// 사용 예시
const facade = new ComputerFacade(new Computer());
facade.turnOn();

Python 예제 보기

class Computer:
    def get_electric_shock(self): print("Ouch!")
    def make_sound(self): print("Beep beep!")
    def show_loading_screen(self): print("Loading..")

class ComputerFacade:
    def __init__(self, computer: Computer):
        self.computer = computer

    def turn_on(self):
        self.computer.get_electric_shock()
        self.computer.make_sound()
        self.computer.show_loading_screen()

# 사용 예시
facade = ComputerFacade(Computer())
facade.turn_on()

6. Flyweight (플라이웨이트)

현실 예시:
찻집에서 손님이 100명 왔을 때 매번 완전히 새로운 찻잔 객체를 100개 찍어내기보다, 동일한 종류의 차(상태가 같은 객체)는 재사용하여 메모리와 자원을 아끼는 방식입니다.

한 줄 정의:
많은 수의 유사한 객체를 효율적으로 공유하여 메모리 사용량을 절감시키는 패턴입니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class KarakTea {}

class TeaMaker {
  constructor() {
    this.availableTea = {};
  }

  make(preference) {
    if (!this.availableTea[preference]) {
      this.availableTea[preference] = new KarakTea();
    }
    return this.availableTea[preference];
  }
}

// 사용 예시
const maker = new TeaMaker();
const tea1 = maker.make('less sugar');
const tea2 = maker.make('less sugar');

console.log(tea1 === tea2); // true (객체 공유)

Python 예제 보기

class KarakTea:
    pass

class TeaMaker:
    def __init__(self):
        self._available_tea = {}

    def make(self, preference: str) -> KarakTea:
        if preference not in self._available_tea:
            self._available_tea[preference] = KarakTea()
        return self._available_tea[preference]

# 사용 예시
maker = TeaMaker()
tea1 = maker.make("less sugar")
tea2 = maker.make("less sugar")
print(tea1 is tea2) # True

7. Proxy (프록시)

현실 예시:
연구실 문을 그냥 열 수도 있지만, 보안 출입 카드키(Proxy)를 거쳐야만 문이 열리도록 출입 통제 기능을 대리하는 것입니다.

한 줄 정의:
다른 객체에 대한 접근을 제어하거나 대리자 역할을 수행하는 객체를 제공합니다 (보안, 캐싱, 지연 로딩 등).

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class LabDoor {
  open() { console.log('Opening lab door'); }
  close() { console.log('Closing lab door'); }
}

class SecuredDoor {
  constructor(door) {
    this.door = door;
  }

  open(password) {
    if (password === 'secret') {
      this.door.open();
    } else {
      console.log('Access denied!');
    }
  }

  close() {
    this.door.close();
  }
}

// 사용 예시
const door = new SecuredDoor(new LabDoor());
door.open('wrong');  // Access denied!
door.open('secret'); // Opening lab door

Python 예제 보기

class LabDoor:
    def open(self): print("Opening lab door")

class SecuredDoor:
    def __init__(self, door: LabDoor):
        self.door = door

    def open(self, password: str):
        if password == "secret":
            self.door.open()
        else:
            print("Access denied!")

# 사용 예시
door = SecuredDoor(LabDoor())
door.open("wrong")  # Access denied!
door.open("secret") # Opening lab door

행동 디자인 패턴 (Behavioral Design Patterns)

한 줄 요약: 객체 간의 책임 분배, 알고리즘 제어 흐름, 그리고 통신 방식을 다루는 패턴입니다.

1. Chain of Responsibility (책임 사슬)

현실 예시:
결제 시스템에서 먼저 계좌 A(잔액 부족) ➔ 카드 B(잔액 부족) ➔ 카카오페이 C(성공)로 순차적으로 처리 권한을 넘겨가며 결제를 완료하는 구조입니다.

한 줄 정의:
요청을 처리할 수 있는 객체들을 사슬(Chain) 형태로 연결하여, 요청이 처리될 때까지 사슬을 따라 전달시킵니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Account {
  setNext(account) {
    this.successor = account;
  }

  pay(amountToPay) {
    if (this.canPay(amountToPay)) {
      console.log(`Paid ${amountToPay} using ${this.name}`);
    } else if (this.successor) {
      console.log(`Cannot pay using ${this.name}. Proceeding..`);
      this.successor.pay(amountToPay);
    } else {
      console.log('None of the accounts have enough balance');
    }
  }

  canPay(amount) {
    return this.balance >= amount;
  }
}

class Bank extends Account {
  constructor(balance) {
    super();
    this.name = 'Bank';
    this.balance = balance;
  }
}

class Paypal extends Account {
  constructor(balance) {
    super();
    this.name = 'Paypal';
    this.balance = balance;
  }
}

// 사용 예시
const bank = new Bank(100);
const paypal = new Paypal(200);

bank.setNext(paypal);
bank.pay(150); // Paid 150 using Paypal

Python 예제 보기

class Account:
    def __init__(self, balance: float):
        self.balance = balance
        self.next_account = None

    def set_next(self, account):
        self.next_account = account

    def pay(self, amount: float):
        if self.balance >= amount:
            print(f"Paid {amount} using {self.__class__.__name__}")
        elif self.next_account:
            self.next_account.pay(amount)
        else:
            print("Cannot pay!")

# 사용 예시
bank = Account(100)
paypal = Account(200)
bank.set_next(paypal)
bank.pay(150) # Paid 150 using Paypal

2. Command (커맨드)

현실 예시:
손님이 주문서(Command)를 작성해서 웨이터(Invoker)에게 주면, 웨이터는 주문 내용을 신경 쓰지 않고 요리사(Receiver)에게 그대로 전달만 합니다. 요청 자체가 독립된 객체가 됩니다.

한 줄 정의:
요청 자체를 독립적인 객체로 캡슐화하여 요청 매개변수화, 작업 취소(Undo), 큐 저장 등을 가능하게 합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Bulb {
  turnOn() { console.log('Light on'); }
  turnOff() { console.log('Light off'); }
}

class TurnOnCommand {
  constructor(bulb) {
    this.bulb = bulb;
  }

  execute() {
    this.bulb.turnOn();
  }
}

class RemoteControl {
  submit(command) {
    command.execute();
  }
}

// 사용 예시
const bulb = new Bulb();
const cmd = new TurnOnCommand(bulb);
const remote = new RemoteControl();
remote.submit(cmd); // Light on

Python 예제 보기

class Bulb:
    def turn_on(self): print("Light on")
    def turn_off(self): print("Light off")

class TurnOnCommand:
    def __init__(self, bulb: Bulb): self.bulb = bulb
    def execute(self): self.bulb.turn_on()

class RemoteControl:
    def submit(self, command): command.execute()

# 사용 예시
bulb = Bulb()
cmd = TurnOnCommand(bulb)
remote = RemoteControl()
remote.submit(cmd) # Light on

➿ 3. Iterator (반복자)

현실 예시:
라디오의 '다음 채널' 버튼을 누르면 내부 회로 구조가 복잡하게 어찌 되어 있든 단순히 순서대로 다음 채널로 넘어가서 청취할 수 있습니다.

한 줄 정의:
컬렉션의 내부 표현 방식을 노출하지 않고 그 안의 요소들에 순차적으로 접근할 수 있는 방법을 제공합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class StationList {
  constructor() {
    this.stations = [];
  }

  addStation(freq) {
    this.stations.push(freq);
  }

  // Symbol.iterator 구현
  *[Symbol.iterator]() {
    for (const station of this.stations) {
      yield station;
    }
  }
}

// 사용 예시
const stations = new StationList();
stations.addStation(89.0);
stations.addStation(101.5);

for (const station of stations) {
  console.log(station);
}

Python 예제 보기

class StationList:
    def __init__(self):
        self.stations = []

    def add_station(self, freq: float):
        self.stations.append(freq)

    def __iter__(self):
        return iter(self.stations)

# 사용 예시
stations = StationList()
stations.add_station(89.0)
stations.add_station(101.5)
for s in stations:
    print(s)

4. Mediator (중재자)

현실 예시:
채팅방(Mediator)이 존재하여 모든 유저가 서로 1:1로 직접 연결될 필요 없이 채팅방 서버 하나만을 통해 메시지를 송수신합니다.

한 줄 정의:
객체 간의 복잡한 상호작용을 중재자 객체에 캡슐화하여 객체 간의 결합도(Coupling)를 획기적으로 낮춥니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class ChatRoom {
  showMessage(user, message) {
    console.log(`[${user.getName()}]: ${message}`);
  }
}

class User {
  constructor(name, chatMediator) {
    this.name = name;
    this.chatMediator = chatMediator;
  }

  getName() {
    return this.name;
  }

  send(message) {
    this.chatMediator.showMessage(this, message);
  }
}

// 사용 예시
const mediator = new ChatRoom();
const john = new User('John', mediator);
john.send('Hello!'); // [John]: Hello!

Python 예제 보기

class ChatRoom:
    def show_message(self, user, message: str):
        print(f"[{user.name}]: {message}")

class User:
    def __init__(self, name: str, mediator: ChatRoom):
        self.name = name
        self.mediator = mediator

    def send(self, message: str):
        self.mediator.show_message(self, message)

# 사용 예시
chat = ChatRoom()
john = User("John", chat)
john.send("Hello!")

5. Memento (메멘토)

현실 예시:
텍스트 에디터에서 글을 쓰다가 Ctrl + Z (Undo)를 누르면 이전 저장 시점(스냅샷)으로 글의 상태가 롤백됩니다.

한 줄 정의:
캡슐화를 저해하지 않으면서 객체의 내부 상태를 스냅샷으로 저장하여 나중에 복원할 수 있게 합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Memento {
  constructor(content) {
    this.content = content;
  }

  getContent() {
    return this.content;
  }
}

class Editor {
  constructor() {
    this.content = '';
  }

  type(text) {
    this.content += text;
  }

  save() {
    return new Memento(this.content);
  }

  restore(memento) {
    this.content = memento.getContent();
  }
}

// 사용 예시
const editor = new Editor();
editor.type('Hello World');
const saved = editor.save();

editor.type(' Extra text');
editor.restore(saved);
console.log(editor.content); // Hello World

Python 예제 보기

class Memento:
    def __init__(self, state: str): self._state = state
    def get_state(self): return self._state

class Editor:
    def __init__(self): self.content = ""
    def type(self, text: str): self.content += text
    def save(self): return Memento(self.content)
    def restore(self, memento: Memento): self.content = memento.get_state()

# 사용 예시
editor = Editor()
editor.type("Hello World")
saved = editor.save()
editor.type(" Extra text")
editor.restore(saved)
print(editor.content) # Hello World

6. Observer (옵저버)

현실 예시:
YouTube 채널 구독과 같습니다. 채널에 새 영상이 업로드(상태 변경)되면 구독(Subscriber/Observer) 중인 시청자들에게 알림이 자동으로 보내집니다.

한 줄 정의:
객체의 상태 변화가 있을 때 이를 구독하고 있는 관찰자들에게 자동으로 알림을 전달하는 일대다 의존 관계 패턴입니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class JobSeeker {
  constructor(name) {
    this.name = name;
  }

  notify(jobTitle) {
    console.log(`Hi ${this.name}, new job posted: ${jobTitle}`);
  }
}

class EmploymentAgency {
  constructor() {
    this.observers = [];
  }

  attach(observer) {
    this.observers.push(observer);
  }

  addJob(jobTitle) {
    this.observers.forEach(obs => obs.notify(jobTitle));
  }
}

// 사용 예시
const agency = new EmploymentAgency();
agency.attach(new JobSeeker('Alice'));
agency.addJob('Backend Developer');

Python 예제 보기

class JobSeeker:
    def __init__(self, name: str): self.name = name
    def notify(self, job_title: str): print(f"Hi {self.name}, new job: {job_title}")

class EmploymentAgency:
    def __init__(self): self.observers = []
    def attach(self, observer: JobSeeker): self.observers.append(observer)
    def add_job(self, title: str):
        for obs in self.observers: obs.notify(title)

# 사용 예시
agency = EmploymentAgency()
agency.attach(JobSeeker("Alice"))
agency.add_job("Backend Developer")

7. Visitor (방문자)

현실 예시:
관광객(Visitor)이 해외 국가를 방문할 때 현지 법이나 규칙을 바꾸지 않고도 관광객 자신의 고유한 동작(사진 찍기, 쇼핑하기 등)을 수행합니다.

한 줄 정의:
객체 구조의 클래스 코드를 변경하지 않고 새로운 연산/기능을 외부 방문자 클래스에 추가할 수 있게 합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Monkey {
  shout() {
    console.log('Ooh oo aa aa!');
  }

  accept(operation) {
    operation.visitMonkey(this);
  }
}

class SpeakOperation {
  visitMonkey(monkey) {
    monkey.shout();
  }
}

// 사용 예시
const monkey = new Monkey();
const speak = new SpeakOperation();
monkey.accept(speak); // Ooh oo aa aa!

Python 예제 보기

class Monkey:
    def shout(self): print("Ooh oo aa aa!")
    def accept(self, operation): operation.visit_monkey(self)

class SpeakOperation:
    def visit_monkey(self, monkey: Monkey): monkey.shout()

# 사용 예시
monkey = Monkey()
speak = SpeakOperation()
monkey.accept(speak)

8. Strategy (전략)

현실 예시:
정렬할 데이터 양에 따라 작은 데이터는 버블 정렬, 큰 데이터는 퀵 정렬로 알고리즘 전략을 런타임에 유연하게 변경합니다.

한 줄 정의:
동일 계열의 알고리즘들을 개별 클래스로 캡슐화하여 런타임에 동적으로 교체해서 사용할 수 있게 합니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class BubbleSort {
  sort(dataset) {
    console.log('Bubble sort applied');
    return dataset.sort();
  }
}

class QuickSort {
  sort(dataset) {
    console.log('Quick sort applied');
    return dataset.sort();
  }
}

class Sorter {
  constructor(strategy) {
    this.strategy = strategy;
  }

  sort(dataset) {
    return this.strategy.sort(dataset);
  }
}

// 사용 예시
const sorter = new Sorter(new BubbleSort());
sorter.sort([3, 1, 2]);

Python 예제 보기

class BubbleSort:
    def sort(self, data):
        print("Bubble sort applied")
        return sorted(data)

class QuickSort:
    def sort(self, data):
        print("Quick sort applied")
        return sorted(data)

class Sorter:
    def __init__(self, strategy): self.strategy = strategy
    def sort(self, data): return self.strategy.sort(data)

# 사용 예시
sorter = Sorter(BubbleSort())
sorter.sort([3, 1, 2])

9. State (상태)

현실 예시:
스마트폰에서 똑같이 화면을 누르더라도 잠금 상태, 통화 상태, 카메라 작동 상태에 따라 각각 완전히 다른 동작을 수행하는 것과 같습니다.

한 줄 정의:
객체의 내부 상태 변경에 따라 객체의 행동을 변경하여, 마치 객체의 클래스가 바뀐 것처럼 동작하게 만듭니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class StateIdle {
  pickUp() {
    console.log('Picked up');
    return new StatePickedUp();
  }
}

class StatePickedUp {
  pickUp() {
    console.log('Already picked up');
    return this;
  }
}

class Phone {
  constructor() {
    this.state = new StateIdle();
  }

  pickUp() {
    this.state = this.state.pickUp();
  }
}

// 사용 예시
const phone = new Phone();
phone.pickUp(); // Picked up
phone.pickUp(); // Already picked up

Python 예제 보기

class StateIdle:
    def pick_up(self):
        print("Picked up")
        return StatePickedUp()

class StatePickedUp:
    def pick_up(self):
        print("Already picked up")
        return self

class Phone:
    def __init__(self): self.state = StateIdle()
    def pick_up(self): self.state = self.state.pick_up()

# 사용 예시
phone = Phone()
phone.pick_up() # Picked up

10. Template Method (템플릿 메서드)

현실 예시:
건축 공정에서 기초 공사 ➔ 벽 세우기 ➔ 지붕 얹기의 큰 틀(스켈레톤)은 일정하지만, 벽을 콘크리트로 할지 목재로 할지의 개별 세부 단계는 상황에 맞춰 다르게 구현합니다.

한 줄 정의:
알고리즘의 골격(뼈대)을 상위 클래스의 메서드에 정의하고, 일부 세부 단계는 하위 클래스에서 오버라이딩하도록 미룹니다.

프로그래밍 예제

JavaScript (Node.js) 예제 보기

class Builder {
  // 템플릿 메서드
  build() {
    this.test();
    this.assemble();
  }

  test() {
    throw new Error('test() 메서드를 구현해야 합니다.');
  }

  assemble() {
    throw new Error('assemble() 메서드를 구현해야 합니다.');
  }
}

class AndroidBuilder extends Builder {
  test() {
    console.log('Testing Android code');
  }

  assemble() {
    console.log('Assembling APK');
  }
}

// 사용 예시
const builder = new AndroidBuilder();
builder.build();

Python 예제 보기

from abc import ABC, abstractmethod

class Builder(ABC):
    # Template method
    def build(self):
        self.test()
        self.assemble()

    @abstractmethod
    def test(self): pass
    @abstractmethod
    def assemble(self): pass

class AndroidBuilder(Builder):
    def test(self): print("Testing Android code")
    def assemble(self): print("Assembling APK")

# 사용 예시
builder = AndroidBuilder()
builder.build()

마무리하며 (Wrap-Up)

이것으로 핵심 23가지 디자인 패턴 정리를 마칩니다!
디자인 패턴은 코드를 무조건 복잡하게 만드는 도구가 아니라, 팀원 간의 공통 언어를 형성하고 유지보수성을 극대화하기 위한 약속입니다. 적재적소에 유연하게 활용해 보세요!

기여 및 피드백 (Contribution)

이슈 제보 (Report issues)
개선 푸시 리퀘스트 (Open Pull Request)
주변 공유 및 전달 (Spread the word)
작성자 인사하기:

라이선스 (License)

AI 네이티브 앱 제작 프로세스

행복한 수지아빠 — Mon, 3 Aug 2026 10:14:31 +0900

사용자 문제 정의부터 디자인, 통합 명세, 구현, 검증까지 연결하는 실무 가이드

1. 문서 개요

목적

이 문서는 AI를 활용해 앱을 만들 때 곧바로 코드를 작성하지 않고, 사용자 문제와 제품 기준을 먼저 구체화하는 작업 절차를 설명한다. 독자는 이 절차를 따라 다음 산출물을 순서대로 만들 수 있다.

사용자 문제 정의
design.md
핵심 화면 시안
통합 기획서 spec.html
전체 화면 목업 design.html
구현된 애플리케이션

완료 상태는 제품 요구사항, 디자인, 데이터 구조, 구현 코드가 서로 일치하고 핵심 사용자 흐름을 실행할 수 있는 상태다.

대상 독자

AI 코딩 도구로 웹 또는 모바일 앱을 만들려는 기획자와 개발자
제품 아이디어를 실제 서비스 명세로 구체화하려는 1인 개발자
AI가 생성한 화면과 코드를 검수해야 하는 제품 책임자

범위

이 문서는 제품 기획과 제작 순서를 다룬다. 특정 AI 도구의 설치 방법, 명령어, 요금, 배포 환경 설정은 다루지 않는다.

미검증 범위: 이 문서는 사용자가 제공한 영상 요약을 기술 문서 형식으로 재구성한 것이다. 영상 원본, 도구의 현재 기능, 실제 구현 결과는 별도로 검증하지 않았다.

2. 핵심 원칙

AI 네이티브 앱 제작의 핵심은 코딩 속도가 아니라 AI가 판단할 수 있는 기준을 먼저 제공하는 것이다. 전체 흐름은 다음과 같다.

아이디어
→ 사용자 문제 정의
→ 디자인 원칙 수립
→ 핵심 화면 탐색
→ 제품·디자인·기술 명세 통합
→ 전체 화면과 상태 설계
→ 구현 전 질의응답
→ 실제 개발
→ 검증과 반복 수정
→ 명세·디자인·코드 동기화
→ 배포

이 과정에서 AI는 여러 대안을 빠르게 생성한다. 사람은 해결할 문제, 디자인의 취향, 기능의 우선순위, 데이터 구조와 최종 품질 기준을 결정한다.

3. 예제 서비스: TasteMaker

TasteMaker는 영화, TV 프로그램, 게임처럼 여러 서비스에 흩어진 개인 취향을 한 페이지에 정리하고 공유하는 프로필 서비스다.

사용자 문제

영화, TV 프로그램, 게임 기록이 서로 다른 서비스에 나뉘어 있어 사용자가 자신의 취향 전체를 한 페이지로 보여주기 어렵다.

주요 기능

좋아하는 영화·TV 프로그램·게임 표시
최근 리뷰와 별점 표시
사용자가 만든 콘텐츠 목록 관리
공개 프로필 공유
회원가입과 온보딩
콘텐츠 추가·수정·정렬

이 예제는 이후 단계에서 어떤 산출물을 만들어야 하는지 설명하기 위한 기준으로 사용한다.

4. 단계별 제작 절차

4.1 사용자 문제 정의

목표

기능 목록을 작성하기 전에 제품이 해결할 사용자 문제를 한 문장으로 정의한다.

작성 항목

이 제품을 사용할 사람은 누구인가?
사용자는 현재 어떤 상황에서 불편을 겪는가?
기존 해결 방법은 왜 충분하지 않은가?
제품을 사용한 뒤 무엇이 달라져야 하는가?

사업화를 전제로 한다면 다음 항목도 조사한다.

실제로 같은 문제를 겪는 사용자가 있는가?
직접 또는 간접 경쟁 서비스는 무엇인가?
사용자가 비용을 지불할 가능성이 있는가?
지속 가능한 수익 모델을 구성할 수 있는가?

개인용 앱이나 내부 도구는 시장성 조사를 줄일 수 있지만, 사용자와 완료 상태는 명확히 정의해야 한다.

산출물 예시

[대상 사용자]는 [현재 상황]에서 [문제]를 겪는다.
기존에는 [대체 방법]을 사용하지만 [한계]가 있다.
이 제품은 [핵심 가치]를 제공해 [기대 결과]를 만든다.

완료 기준

특정 기능명을 사용하지 않고도 문제를 설명할 수 있다.
대상 사용자와 사용 상황이 드러난다.
제품이 제공할 변화가 한 문장으로 정리된다.
사업용 제품이라면 경쟁 서비스와 지불 가능성을 조사할 계획이 있다.

4.2 디자인 레퍼런스 수집과 design.md 작성

목표

“예쁘게 만들어 달라”는 추상적인 요청을 시각적 기준과 구현 가능한 디자인 규칙으로 바꾼다.

절차

Mobbin, Dribbble, 실제 앱 화면 등에서 레퍼런스를 수집한다.
각 레퍼런스에서 채택할 요소와 제외할 요소를 구분한다.
제품의 콘텐츠와 사용 맥락에 맞는 디자인 원칙을 정한다.
결정한 내용을 design.md에 기록한다.

레퍼런스는 방향을 찾는 자료로만 사용하고 화면을 그대로 복제하지 않는다.

design.md 권장 구조

# Design Direction

## Design Principles
- 콘텐츠가 인터페이스보다 먼저 보이게 한다.
- 장식 요소는 사용자의 판단을 방해하지 않는 범위에서 사용한다.

## Color
- 배경색:
- 기본 텍스트:
- 보조 텍스트:
- 강조색:
- 상태 색상:

## Typography
- 제목:
- 본문:
- 보조 정보:

## Spacing and Layout
- 기본 간격 단위:
- 최대 콘텐츠 너비:
- 카드 간격:

## Components
- 버튼:
- 카드:
- 입력창:
- 모달 및 시트:

## Content Density
- 한 화면에 노출할 정보량:
- 모바일 축약 규칙:

TasteMaker의 디자인 방향은 인터페이스를 조용하고 단순하게 유지하고, 영화와 게임의 커버 이미지가 화면의 주요 색상을 담당하게 하는 것이다.

완료 기준

색상, 타이포그래피, 간격, 카드와 버튼 규칙이 정의되어 있다.
레퍼런스에서 가져올 원칙과 복제하지 않을 요소가 구분되어 있다.
AI가 서로 다른 화면에서도 같은 시각 언어를 적용할 수 있다.

4.3 핵심 화면 탐색

목표

전체 화면을 만들기 전에 제품의 가치와 디자인 방향을 가장 잘 보여주는 화면 두 개를 설계한다.

TasteMaker에서는 다음 화면을 먼저 만든다.

비로그인 사용자가 보는 랜딩 페이지
영화·TV 프로그램·게임 취향을 보여주는 공개 프로필

절차

design.md와 사용자 문제를 AI 디자인 도구에 제공한다.
서로 다른 레이아웃과 테마의 시안을 요청한다.
각 시안을 콘텐츠 우선순위와 사용성 기준으로 비교한다.
적합한 방향을 하나 선택한다.
불필요한 요소를 제거하고 배치, 밀도, 문구를 반복 수정한다.

시안 변형 예시는 다음과 같다.

행 중심 레이아웃
그리드 중심 에디토리얼 레이아웃
라이트 모드
다크 모드

피드백 작성 원칙

“더 예쁘게”처럼 평가 기준이 없는 표현보다 대상과 변경 내용을 함께 적는다.

[대상 화면 또는 컴포넌트]에서
[현재 문제]가 있으므로
[구체적인 변경]을 적용한다.
[변경 후 확인할 기준]은 다음과 같다.

예:

사용하지 않는 팔로우 버튼을 삭제한다.
즐겨찾기 콘텐츠를 한 행에 6개 배치한다.
콘텐츠 행에 좌우 이동 버튼을 추가한다.
리뷰는 작은 카드 그리드 대신 전체 너비의 한 줄 구조로 표시한다.
공개 프로필 왼쪽에 섹션 빠른 이동 메뉴를 배치한다.
랜딩 페이지에서 실제 공개 프로필 예시를 크게 보여준다.

완료 기준

선택한 화면이 제품의 핵심 가치를 설명한다.
콘텐츠 우선순위와 화면 밀도가 정리되어 있다.
두 핵심 화면이 같은 컴포넌트와 시각 규칙을 사용한다.
선택하지 않은 시안과 선택 이유를 기록했다.

4.4 통합 기획서 spec.html 작성

목표

제품 요구사항, 디자인 시스템, 기술 설계를 하나의 기준 문서로 통합한다.

spec.html은 최소한 Product, Design, Tech의 세 영역으로 구성한다.

Product 영역

사용자 문제와 대상 사용자
제품 목표와 성공 기준
핵심 기능과 우선순위
화면별 요구사항
기본 상태와 예외 상태
사용자 권한과 접근 범위

Design 영역

디자인 원칙
색상과 타이포그래피
간격과 레이아웃 규칙
공통 UI 컴포넌트
컴포넌트별 상태와 사용 규칙
반응형 동작

Tech 영역

프런트엔드와 백엔드 기술
인증 방식
데이터베이스
데이터 스키마와 관계
외부 API와 의존성
오류 처리와 로딩 전략
구현 제약과 미결정 사항

공통 컴포넌트 정의

컴포넌트마다 다음 항목을 기록한다.

항목설명

이름	코드와 디자인에서 공통으로 사용할 이름
목적	사용자가 이 컴포넌트로 수행하는 작업
변형	크기, 강조 수준, 용도별 형태
상태	기본, 호버, 포커스, 비활성, 로딩, 오류
콘텐츠 규칙	허용 길이, 줄바꿈, 생략 방식
접근성	키보드 조작, 레이블, 대비 등

데이터 스키마 정의

데이터 모델마다 다음 항목을 명시한다.

엔터티 이름과 역할
필드명, 데이터 형식, 필수 여부
고유값과 기본값
엔터티 간 관계
생성·수정·삭제 규칙
공개 정보와 비공개 정보
정렬과 검색에 필요한 인덱스

스키마가 확정되지 않은 항목은 추정하여 채우지 않고 미결정으로 표시한 뒤 구현 전에 질문한다.

완료 기준

모든 핵심 기능이 특정 화면 또는 사용자 흐름에 연결된다.
공통 컴포넌트의 이름과 상태가 정의되어 있다.
데이터 스키마가 화면의 입력·출력과 연결되어 있다.
미결정 사항과 결정 책임자가 구분되어 있다.

4.5 전체 화면과 상태 설계

목표

정상 상태뿐 아니라 실제 사용 중 나타날 수 있는 빈 화면, 오류, 권한, 긴 콘텐츠와 작은 화면까지 설계한다.

TasteMaker의 화면 목록

랜딩 페이지
공개 프로필
본인 프로필 편집
콘텐츠 추가
리뷰 작성·수정
전체 영화·게임 목록
콘텐츠 상세 시트
회원가입과 온보딩
사용자 핸들 선택
좋아하는 콘텐츠 6개 선택
프로필 공유

화면별 필수 상태

상태	확인할 내용
기본	대표 데이터가 있을 때의 정상 화면
빈 화면	데이터가 없을 때의 안내와 다음 행동
최초 가입	사용자가 처음 진입했을 때의 안내
로딩	대기 중인 영역과 사용자 조작 가능 범위
오류	오류 설명, 재시도, 안전한 이탈 방법
검색 결과 없음	검색어 수정 또는 초기화 방법
저장 전·후	미저장 변경과 저장 성공 여부
권한 없음	접근 제한 이유와 가능한 다음 행동
긴 콘텐츠	긴 제목, 리뷰, 사용자 이름 처리
작은 화면	모바일 배치, 축약, 탐색 방식

화면 명세 템플릿

화면 이름:
사용자 목표:
진입 조건:
주요 데이터:
주요 행동:
공통 컴포넌트:
정상 상태:
빈 상태:
로딩 상태:
오류 상태:
권한 조건:
모바일 규칙:
완료 조건:

완료 기준

모든 핵심 사용자 흐름에 시작점과 종료점이 있다.
각 화면에 필요한 데이터와 사용자 행동이 정의되어 있다.
빈 상태, 로딩, 오류, 권한 없음 상태를 확인했다.
긴 콘텐츠와 모바일 화면에서 레이아웃이 깨지지 않는 기준이 있다.

4.6 구현 전 검토와 실제 개발

목표

코딩 에이전트가 임의로 결정해야 하는 부분을 줄이고, 합의된 명세와 디자인을 코드로 옮긴다.

입력 파일

spec.html: 제품, 디자인, 기술 요구사항
design.html: 전체 화면과 상태의 목업

구현 전 요청 예시

spec.html과 design.html을 검토하세요.
아직 구현하지 말고, 두 문서가 충돌하거나 구현에 필요한 정보가
빠진 부분을 질문 목록으로 정리하세요.

각 질문에는 다음 내용을 포함하세요.
1. 관련 화면 또는 요구사항
2. 현재 모호한 점
3. 결정하지 않았을 때 구현에 미치는 영향
4. 선택 가능한 대안

구현 순서

코딩 에이전트의 질문에 답하고 미결정 사항을 확정한다.
핵심 사용자 흐름부터 수직으로 구현한다.
로컬 환경에서 화면과 동작을 확인한다.
디자인과 다른 부분, 누락 기능, 상태 처리를 수정한다.
인증과 데이터베이스를 연결한다.
실제 데이터의 생성, 조회, 수정, 삭제를 확인한다.
변경된 요구사항을 spec.html과 design.html에 반영한다.

검수 항목

리뷰 영역 등 필수 콘텐츠가 빠지지 않았는가?
카드의 호버 상태처럼 상호작용 조건이 디자인과 일치하는가?
좌우 이동, 정렬, 필터 등 탐색 동작이 요구사항과 일치하는가?
여백, 글꼴, 정렬, 반응형 동작이 디자인과 일치하는가?
인증 상태에 따라 접근 권한이 올바르게 달라지는가?
입력한 데이터가 실제 데이터베이스에 저장되고 다시 조회되는가?

완료 기준

구현 전 질문에 답했으며 남은 미결정 사항이 표시되어 있다.
핵심 사용자 흐름을 로컬 환경에서 처음부터 끝까지 실행할 수 있다.
요구사항, 디자인, 구현의 차이를 기록하고 해소했다.
코드 변경으로 요구사항이 달라졌다면 문서도 함께 갱신했다.

5. 산출물 간 추적 관계

각 산출물은 독립 문서가 아니라 다음 단계의 입력이다.

산출물	포함할 내용	다음 단계에서의 용도
문제 정의	사용자, 상황, 문제, 기대 변화	기능과 우선순위 판단
design.md	디자인 원칙과 시각 규칙	핵심 화면 시안 생성
핵심 화면	선택한 레이아웃과 콘텐츠 구조	상세 요구사항 발견
spec.html	제품·디자인·기술 명세	전체 화면 설계와 구현 기준
design.html	전체 화면과 상태	구현 결과의 시각적 기준
애플리케이션 코드	실제 동작	테스트와 배포 대상

요구사항이 바뀌면 영향을 받는 산출물을 함께 수정한다. 예를 들어 프로필에서 즐겨찾기 개수가 6개에서 8개로 바뀌었다면 Product 요구사항, 컴포넌트 규칙, 화면 목업, 데이터 검증 규칙과 구현 코드를 모두 확인한다.

6. 단계별 품질 게이트

다음 단계로 넘어가기 전에 각 질문에 답한다.

문제 정의 완료

대상 사용자가 구체적인가?
사용 상황과 문제가 한 문장으로 설명되는가?
기능이 아니라 사용자의 변화를 중심으로 작성했는가?

디자인 방향 완료

레퍼런스의 채택·제외 기준이 있는가?
색상, 글꼴, 간격, 컴포넌트 원칙이 있는가?
제품 콘텐츠가 시각적 장식보다 우선하는가?

핵심 화면 완료

최소 두 가지 이상의 대안을 비교했는가?
선택 이유를 설명할 수 있는가?
불필요한 요소를 제거했는가?

통합 명세 완료

기능이 화면과 사용자 흐름에 연결되는가?
공통 컴포넌트와 상태가 정의되어 있는가?
데이터 스키마와 권한 규칙이 정의되어 있는가?
미결정 사항을 질문 목록으로 분리했는가?

전체 디자인 완료

정상·빈·로딩·오류 상태가 있는가?
권한 없음과 검색 결과 없음 상태가 있는가?
긴 콘텐츠와 모바일 화면을 확인했는가?

구현 완료

핵심 흐름을 실제로 실행했는가?
저장한 데이터를 다시 조회할 수 있는가?
명세와 디자인의 차이를 수정했는가?
변경된 코드와 문서를 동기화했는가?

7. 자주 발생하는 실패와 대응

추상적인 디자인 요청

증상: 화면마다 전형적인 색상과 구성요소가 반복되고 제품의 개성이 드러나지 않는다.

확인: design.md에 콘텐츠 우선순위, 제외할 스타일, 컴포넌트 규칙이 있는지 점검한다.

대응: 실제 레퍼런스에서 채택할 원칙을 뽑고 색상, 간격, 밀도와 컴포넌트 상태를 명시한다.

첫 번째 시안을 완성품으로 사용

증상: 불필요한 버튼, 배지, 문구가 남고 콘텐츠 구조가 사용자 목표와 맞지 않는다.

확인: 서로 다른 구조의 대안을 비교했는지, 삭제 중심의 피드백을 진행했는지 확인한다.

대응: 레이아웃 대안을 만든 뒤 콘텐츠 우선순위, 정보 밀도와 사용자 행동을 기준으로 하나를 선택한다.

정상 화면만 설계

증상: 실제 데이터가 없거나 오류가 발생했을 때 화면과 다음 행동이 정의되지 않는다.

확인: 화면 명세에 빈 상태, 로딩, 오류, 권한과 모바일 항목이 있는지 확인한다.

대응: 상태 매트릭스를 만들고 각 상태의 메시지, 행동과 복구 경로를 정의한다.

화면마다 다른 컴포넌트 생성

증상: 같은 역할의 버튼과 카드가 화면마다 다른 크기, 색상, 동작을 사용한다.

확인: 컴포넌트 이름, 변형과 상태가 spec.html에 정의되어 있는지 확인한다.

대응: 공통 컴포넌트 목록을 만들고 디자인과 코드에서 같은 이름을 사용한다.

문서와 코드 불일치

증상: 구현은 변경됐지만 명세나 목업에는 이전 동작이 남아 있다.

확인: 변경 사항이 제품 요구사항, 디자인, 데이터와 코드 중 어디에 영향을 주는지 추적한다.

대응: 구현 작업의 완료 조건에 관련 문서 갱신을 포함한다.

8. 운영 원칙

기획에 충분한 시간 배정

제공된 영상은 전체 제작 시간의 최소 50%를 사전 기획에 투자하라고 제안한다. 이 비율은 이 문서에서 독립적으로 검증하지 않았다. 실무에서는 데이터베이스 구조, 인증 방식, 화면 구조, 핵심 사용자 흐름과 공통 컴포넌트처럼 변경 영향이 큰 결정을 구현 전에 우선 검토한다.

구체적인 반복 피드백

AI의 첫 결과는 검토할 초안으로 취급한다. 피드백에는 대상, 문제, 변경 내용과 확인 기준을 포함한다. 시각적 취향만 말하지 않고 사용자 목표와 제품 원칙을 근거로 판단한다.

단일 기준 문서 유지

spec.html과 design.html을 구현의 기준으로 사용한다. 코드에서 요구사항이 바뀌면 관련 문서도 같은 작업 범위에서 수정한다. 문서와 코드가 충돌하면 어느 쪽이 최신 결정인지 확인한 뒤 한쪽을 임의로 덮어쓰지 않는다.

9. 최종 완료 정의

다음 조건을 모두 충족하면 제작 프로세스가 완료된 것으로 판단한다.

해결할 사용자 문제와 대상 사용자가 명확하다.
선택한 디자인 방향과 선택 이유가 문서화되어 있다.
전체 기능, 화면, 상태, 컴포넌트와 데이터 스키마가 정의되어 있다.
구현 전에 모호한 요구사항을 질문하고 결정했다.
핵심 사용자 흐름이 실제 환경에서 동작한다.
빈 상태, 로딩, 오류, 권한과 모바일 화면을 검증했다.
명세, 디자인과 코드가 같은 요구사항을 반영한다.
배포 전 테스트 결과와 남은 미검증 항목이 기록되어 있다.

10. 결론

AI 네이티브 앱 제작은 AI에게 한 번의 명령으로 완성품을 요청하는 과정이 아니다. 사용자 문제를 정의하고, 디자인의 판단 기준을 만들고, 핵심 화면으로 제품 구조를 탐색한 뒤, 제품·디자인·기술 명세를 구현 가능한 수준으로 연결하는 과정이다.

AI는 대안 생성과 구현 속도를 높이는 역할을 맡는다. 사람은 어떤 문제를 해결할지, 어떤 화면이 더 적합한지, 무엇을 삭제할지, 어떤 데이터 구조와 품질 기준을 채택할지 결정한다. 따라서 최종 품질은 코드 생성 속도뿐 아니라 기획, 디자인 판단, 명세 작성과 검수 능력에 달려 있다.

Codex에서 GPT-5.6 Luna를 서브에이전트로 사용하는 방법

행복한 수지아빠 — Sat, 1 Aug 2026 18:40:46 +0900

이 문서는 GPT-5.6 Sol을 메인 오케스트레이터로 사용하면서 GPT-5.6 Luna를 서브에이전트로 실행하는 로컬 설정을 기록한 운영 가이드다. Codex 업데이트나 설정 초기화 후 Luna 서브에이전트가 보이지 않을 때 이 문서를 따라 다시 설정하고 검증한다.

현재 확인된 정상 구성

2026년 8월 1일 기준으로 다음 구성이 실제 실행까지 확인됐다.

메인 모델: gpt-5.6-sol
서브에이전트 모델: gpt-5.6-luna
Luna 다중 에이전트 프로토콜: v2
Luna 추론 수준: low, medium, high, xhigh, max
실제 검증 결과: Luna 자식 에이전트가 생성되고 LUNA_SUBAGENT_OK를 반환함
검증 당시 데스크톱 내장 Codex: 0.146.0-alpha.9.2
검증 당시 터미널 Codex: 0.146.0

시작하기 전에: Codex 경로 설정

이 문서의 명령은 macOS와 Linux의 Bash/Zsh 셸을 기준으로 한다. 먼저 현재 터미널에서 Codex 데이터 디렉터리를 CODEX_DIR 변수로 지정한다.

export CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
printf 'Codex directory: %s\n' "$CODEX_DIR"

CODEX_HOME을 따로 설정했다면 그 경로를 사용한다.
별도 설정이 없다면 현재 사용자의 기본 경로인 $HOME/.codex를 사용한다.
이후 터미널을 새로 열었다면 위 명령을 다시 실행한다.
Windows에서는 Codex 데이터 디렉터리를 확인한 뒤 PowerShell 환경 변수와 경로 표기법에 맞게 명령을 바꿔야 한다.

이 문서에서 사용하는 파일은 다음과 같다.

$CODEX_DIR/config.toml
$CODEX_DIR/models_cache.json
$CODEX_DIR/models-luna-v2.json

models_cache.json은 Codex가 내려받은 원본 모델 카탈로그다. 이 파일을 직접 수정하지 않고 복사본인 models-luna-v2.json에서 Luna 항목만 v2로 바꾼다.

이 설정은 로컬 모델 카탈로그 오버라이드다. Codex 업데이트로 공식 카탈로그나 서브에이전트 동작 방식이 바뀌면 더 이상 필요하지 않거나 작동하지 않을 수 있다. 업데이트 후에는 반드시 실제 자식 에이전트 실행까지 확인한다.

1. 현재 설정 확인

터미널에서 다음 명령을 실행한다.

grep -nE 'model_catalog_json|multi_agent' "$CODEX_DIR/config.toml"

jq '.models[]
  | select(.slug == "gpt-5.6-luna")
  | {
      slug,
      multi_agent_version,
      supported_reasoning_levels
    }' "$CODEX_DIR/models-luna-v2.json"

정상이라면 다음 두 조건을 만족해야 한다.

model_catalog_json = "/absolute/path/to/codex-home/models-luna-v2.json"
multi_agent = true

Luna 모델 정보에는 다음 값이 있어야 한다.

{
  "slug": "gpt-5.6-luna",
  "multi_agent_version": "v2"
}

파일이 없거나 값이 다르면 다음 절차로 다시 만든다.

2. Luna V2 모델 카탈로그 다시 만들기

먼저 원본 모델 캐시와 현재 설정을 백업한다.

mkdir -p "$CODEX_DIR/backups/luna-v2-setup"

cp "$CODEX_DIR/models_cache.json" \
   "$CODEX_DIR/backups/luna-v2-setup/models_cache.json"

cp "$CODEX_DIR/config.toml" \
   "$CODEX_DIR/backups/luna-v2-setup/config.toml"

원본 카탈로그를 복사하고 Luna 항목만 v2로 변경한다.

cp "$CODEX_DIR/models_cache.json" \
   "$CODEX_DIR/models-luna-v2.json"

python3 - <<'PY'
import json
import os
from pathlib import Path

codex_dir = Path(os.environ["CODEX_DIR"]).expanduser().resolve()
catalog_path = codex_dir / "models-luna-v2.json"
data = json.loads(catalog_path.read_text(encoding="utf-8"))
models = data.get("models", [])

matches = [
    model
    for model in models
    if model.get("slug") == "gpt-5.6-luna"
]

if len(matches) != 1:
    raise SystemExit(
        f"gpt-5.6-luna 항목이 정확히 1개여야 합니다. 현재: {len(matches)}개"
    )

matches[0]["multi_agent_version"] = "v2"

temporary_path = catalog_path.with_suffix(".json.tmp")
temporary_path.write_text(
    json.dumps(data, ensure_ascii=False, indent=2) + "\n",
    encoding="utf-8",
)
temporary_path.replace(catalog_path)

print("gpt-5.6-luna multi_agent_version=v2 설정 완료")
PY

명령이 Luna 항목을 찾지 못하면 작업을 중단한다. 다른 모델을 Luna로 추정해 바꾸면 안 된다. 먼저 Codex를 업데이트하거나 models_cache.json에 Luna가 제공되는지 확인한다.

3. `config.toml` 연결

$CODEX_DIR/config.toml의 최상위 영역에 다음 설정을 둔다. 첫 번째 [섹션]이 시작되기 전에 있어야 한다.

먼저 현재 사용자에게 맞는 설정 한 줄을 출력한다.

printf 'model_catalog_json = "%s/models-luna-v2.json"\n' "$CODEX_DIR"

출력된 절대경로를 복사해 config.toml에 넣는다. 예시는 다음과 같다.

model = "gpt-5.6-sol"
model_catalog_json = "/absolute/path/to/codex-home/models-luna-v2.json"

기존 [features] 섹션에는 다음 값을 추가하거나 확인한다.

[features]
multi_agent = true

주의 사항:

model_catalog_json을 [features]나 [projects] 아래에 넣으면 안 된다.
TOML 문자열 안에서는 $HOME이나 $CODEX_DIR 같은 셸 변수가 자동으로 확장되지 않는다. 반드시 앞의 printf 명령으로 확인한 절대경로를 넣는다.
같은 키를 두 번 선언하면 TOML 로딩 오류가 날 수 있다.
기존 [features] 섹션이 있으면 새 섹션을 하나 더 만들지 말고 그 안에 추가한다.
메인 모델을 Sol로 유지하려면 model = "gpt-5.6-sol"을 그대로 둔다.

설정을 저장한 뒤 파싱 상태를 확인한다.

codex doctor --summary

config.load가 실패한다면 앱을 재시작하기 전에 config.toml의 중복 키와 섹션 위치부터 고친다.

4. Codex 완전 재시작

실행 중인 Codex는 시작 시 읽은 모델 카탈로그와 도구 스키마를 계속 사용할 수 있다. 설정 파일만 바꿔서는 이미 열린 작업에 Luna가 나타나지 않을 수 있다.

진행 중인 작업을 마친다.
ChatGPT/Codex 데스크톱 앱을 ⌘Q로 완전히 종료한다.
터미널에서 별도 codex 프로세스가 실행 중이면 함께 종료한다.
데스크톱 앱을 다시 실행한다.
기존 작업이 아니라 새 작업에서 Luna 서브에이전트를 검증한다.

강제 종료나 macOS 재부팅은 필수 조건이 아니다. 앱을 정상적으로 완전히 종료했다가 다시 여는 것으로 충분하다.

5. Luna 서브에이전트 실제 실행

Luna를 확실히 사용하려면 서브에이전트 생성 시 모델을 명시해야 한다.

model: gpt-5.6-luna
reasoning_effort: max
fork_turns: none

fork_turns는 none 또는 최근 턴 수처럼 제한된 값을 사용한다. 전체 대화 기록을 상속하는 생성 방식은 부모 모델과 추론 수준을 그대로 물려받으므로 Luna 모델 오버라이드를 적용할 수 없다.

사용자가 Codex에 요청할 때는 다음과 같이 작성할 수 있다.

메인 Sol이 작업을 조율하고, 실제 하위 작업은
gpt-5.6-luna / reasoning max 서브에이전트로 실행해 줘.
Luna 생성 시 모델을 명시하고 fork_turns는 none 또는 제한된 턴 수를 사용해 줘.

Luna는 max까지 지원한다. ultra를 지정하면 모델 검증 단계에서 거부될 수 있다.

6. 빠른 스모크 테스트

새 작업에서 다음과 같이 요청한다.

gpt-5.6-luna, reasoning max로 읽기 전용 서브에이전트 한 개를 생성해 줘.
그 에이전트는 다른 도구를 사용하지 말고 LUNA_SUBAGENT_OK만 반환하게 해 줘.
실행 후 자식 세션의 실제 model과 reasoning_effort도 확인해 줘.

성공 판정은 다음 세 조건을 모두 만족해야 한다.

자식 생성 요청이 모델 검증 단계에서 거부되지 않는다.
자식이 LUNA_SUBAGENT_OK를 반환한다.
자식 rollout의 turn_context에 model="gpt-5.6-luna"와 reasoning_effort="max"가 기록된다.

최근 자식 세션에서 모델 기록을 찾으려면 다음 명령을 사용할 수 있다.

grep -R -l '"model":"gpt-5.6-luna"' \
  "$CODEX_DIR/sessions" |
  tail -n 5

찾은 rollout 파일에서 turn_context를 확인한다.

jq -c '
  select(.type == "turn_context")
  | {
      model: .payload.model,
      reasoning_effort:
        .payload.collaboration_mode.settings.reasoning_effort
    }
' /절대/경로/rollout-파일.jsonl

정상 결과 예시는 다음과 같다.

{
  "model": "gpt-5.6-luna",
  "reasoning_effort": "max"
}

에이전트가 자기 모델을 말로 주장하는 것만으로는 충분하지 않다. 반드시 자식 세션의 turn_context를 확인한다.

7. 문제가 생겼을 때

`gpt-5.6-luna`가 허용 모델 목록에 없음

다음 항목을 순서대로 확인한다.

model_catalog_json 경로가 정확한가
models-luna-v2.json에 Luna 항목이 있는가
Luna의 multi_agent_version이 v2인가
[features]의 multi_agent가 true인가
설정 변경 후 앱을 완전히 재시작했는가
재시작 후 만든 새 작업에서 테스트했는가

Luna를 지정했는데 Sol 자식이 실행됨

다음 원인이 가장 흔하다.

생성 요청에서 model을 생략함
부모의 전체 대화 기록을 그대로 상속함
자동 오케스트레이션에 맡기고 Luna 사용을 명시하지 않음

Luna를 강제하려면 model=gpt-5.6-luna와 제한된 fork_turns를 함께 지정한다.

`reasoning_effort`가 거부됨

Luna에는 low, medium, high, xhigh, max 중 하나를 사용한다. ultra는 사용하지 않는다.

업데이트 후 다시 작동하지 않음

업데이트된 $CODEX_DIR/models_cache.json에서 Luna의 공식 multi_agent_version을 먼저 확인한다.

jq '.models[]
  | select(.slug == "gpt-5.6-luna")
  | {
      slug,
      multi_agent_version,
      supported_reasoning_levels
    }' "$CODEX_DIR/models_cache.json"

공식 값이 이미 v2라면 별도 오버라이드가 필요하지 않을 수 있다.
공식 값이 v1이면 이 문서의 절차로 별도 카탈로그를 다시 만든다.
Luna 항목 자체가 없으면 임의로 모델 항목을 만들지 않는다.
모델은 보이지만 생성 도구가 거부한다면 현재 Codex 버전의 서브에이전트 도구 스키마가 Luna를 허용하는지 확인한다.

8. 원상 복구

로컬 오버라이드를 제거하려면 앱을 완전히 종료한 뒤 config.toml에서 다음 줄을 삭제한다.

model_catalog_json = "/absolute/path/to/codex-home/models-luna-v2.json"

models-luna-v2.json은 즉시 삭제하지 말고 보관해도 된다. 그다음 앱을 다시 실행하면 Codex가 기본 모델 카탈로그를 사용한다.

백업한 설정으로 되돌려야 할 때는 앱을 종료한 상태에서 백업 내용을 확인한 뒤 복원한다.

cp "$CODEX_DIR/backups/luna-v2-setup/config.toml" \
   "$CODEX_DIR/config.toml"

복원 후에는 codex doctor --summary로 설정 파싱 여부를 확인하고 앱을 다시 실행한다.

PixelRAG: PDF와 이미지를 화면 그대로 검색하는 시각 자료용 RAG

행복한 수지아빠 — Thu, 30 Jul 2026 11:33:10 +0900

1. 개요

PixelRAG는 PDF, 이미지, 웹페이지를 텍스트로 변환하지 않고 화면 이미지 자체를 검색 대상으로 사용하는 시각 자료용 RAG(Retrieval-Augmented Generation) 프로젝트입니다.

일반적인 문서 RAG는 PDF에서 텍스트를 추출한 뒤 문단 단위로 나누어 검색합니다. 반면 PixelRAG는 문서 페이지를 이미지로 저장하고, 비전·언어 임베딩 모델을 이용해 질문과 관련된 페이지를 찾습니다.

이 방식은 다음과 같이 시각적 구조가 중요한 문서에 적합합니다.

표와 차트가 많은 보고서
그림과 설명이 결합된 교재
PPT를 변환한 PDF
인포그래픽
제품 매뉴얼
스캔 문서
시스템 구성도와 설계 도면
웹페이지 UI

PixelRAG는 완성된 문서 채팅 서비스라기보다, 이러한 자료를 검색하기 위한 픽셀 기반 RAG 파이프라인에 가깝습니다.

2. 핵심 처리 구조

PixelRAG의 기본 처리 흐름은 다음과 같습니다.

PDF·이미지·웹페이지 입력
          ↓
페이지를 스크린샷 또는 이미지 타일로 변환
          ↓
Qwen3-VL-Embedding-2B로 이미지 임베딩 생성
          ↓
FAISS 또는 Qdrant에 벡터 저장
          ↓
사용자 질문을 벡터로 변환
          ↓
질문과 관련된 페이지 이미지 검색
          ↓
검색된 이미지를 비전 언어 모델이 분석
          ↓
답변과 출처 페이지 제공

핵심은 문서를 OCR 텍스트로 변환한 뒤 검색하는 것이 아니라, 문서의 시각적 표현을 유지한 상태에서 검색한다는 점입니다.

3. 일반 문서 RAG와의 차이

구분일반 문서 RAGPixelRAG

문서 처리	PDF에서 텍스트 추출	PDF를 페이지 이미지로 변환
검색 단위	문장 또는 문단	페이지 또는 이미지 타일
임베딩 대상	텍스트	이미지와 텍스트의 시각적 의미
표·차트 처리	추출 과정에서 구조가 깨질 수 있음	원래 배치와 형태 유지
OCR 의존성	높음	상대적으로 낮음
주요 대상	텍스트 중심 문서	교재·보고서·도면·인포그래픽
검색 결과	관련 텍스트 조각	관련 페이지 또는 이미지 영역

일반 RAG에서는 표의 행과 열, 이미지와 설명의 위치 관계, 페이지 레이아웃 등이 텍스트 추출 과정에서 사라질 수 있습니다.

PixelRAG는 페이지를 이미지로 다루기 때문에 이러한 시각적 관계를 유지할 수 있습니다.

4. 검색 예시

다음과 같은 PDF가 있다고 가정하겠습니다.

페이지내용

1페이지	회사 소개
2페이지	PixelRAG 시스템 구성도
3페이지	매출 현황 표
4페이지	제품 이미지

사용자가 다음과 같이 질문합니다.

PixelRAG 시스템 구조도를 보여줘.

PixelRAG는 OCR로 추출한 문장을 찾는 대신, 질문과 시각적으로 관련된 2페이지 이미지를 검색 결과로 반환할 수 있습니다.

공식 예제에서도 PDF를 인덱싱한 후 다음과 같은 질문으로 구성도가 포함된 페이지를 검색합니다.

Overview of PixelRAG and the diagram

따라서 PixelRAG가 담당하는 핵심 역할은 다음과 같이 정리할 수 있습니다.

사용자의 질문과 가장 관련된 PDF 페이지 또는 이미지 영역을 시각적으로 검색한다.

5. PDF를 업로드하면 바로 질문할 수 있는가

기술적으로 구현할 수 있지만, 질문하기 전에 문서 인덱싱 과정이 필요합니다.

PixelRAG는 사용자가 질문할 때마다 PDF 전체를 처음부터 분석하지 않습니다. 문서를 최초로 등록할 때 페이지별 임베딩을 생성하고, 이후에는 만들어진 벡터 인덱스를 이용해 관련 페이지를 검색합니다.

기본 작업 순서는 다음과 같습니다.

5.1 입력 문서 지정

source:
  type: local
  path: ./paper.pdf

5.2 이미지 임베딩 모델 지정

embed:
  model: Qwen/Qwen3-VL-Embedding-2B

5.3 인덱스 생성

pixelrag index build

5.4 검색 API 실행

pixelrag serve \
  --index-dir ./paper_index \
  --port 30001

인덱스 생성이 완료되면 애플리케이션은 사용자의 질문을 검색 API로 전달하고, 관련성이 높은 페이지 이미지를 받을 수 있습니다.

공식 README에 기재된 예시 기준으로 샘플 PDF 인덱싱 시간은 다음과 같습니다.

Apple M 시리즈: 약 3분
GPU 환경: 약 1분

문서 크기, 페이지 수, 이미지 해상도, 하드웨어 사양에 따라 실제 처리 시간은 달라질 수 있습니다.

6. PixelRAG가 담당하는 범위

PixelRAG의 주요 역할은 관련 이미지 검색입니다.

검색된 페이지를 읽고 자연어 답변을 생성하려면 별도의 비전 언어 모델(VLM)을 연결해야 합니다.

예를 들어 다음 모델을 답변 생성 단계에 사용할 수 있습니다.

Qwen3-VL
GPT 비전 지원 모델
Claude 비전 지원 모델
기타 이미지 입력을 지원하는 멀티모달 모델

전체 문서 채팅 시스템에서는 PixelRAG와 답변 생성 모델의 역할이 구분됩니다.

구성 요소담당 역할

PixelRAG	질문과 관련된 페이지 또는 이미지 영역 검색
벡터 데이터베이스	이미지 임베딩 저장 및 유사도 검색
비전 언어 모델	검색된 이미지의 내용 분석
LLM	최종 답변 구성
프런트엔드	파일 업로드, 질문 입력, 답변 및 출처 표시

7. 문서 채팅 서비스 구성 예시

ChatPDF와 같은 서비스를 만들려면 PixelRAG 외에 업로드, 작업 관리, 답변 생성, 출처 표시 기능을 추가해야 합니다.

Next.js 파일 업로드 화면
          ↓
PDF 원본 저장
          ↓
인덱싱 작업 등록
          ↓
페이지 이미지 생성
          ↓
PixelRAG 임베딩 및 인덱스 생성
          ↓
사용자 질문 입력
          ↓
관련 페이지 이미지 검색
          ↓
비전 언어 모델이 페이지 분석
          ↓
답변과 PDF 페이지 출처 표시

필요한 주요 구성 요소

파일 업로드 기능
사용자가 PDF나 이미지를 업로드할 수 있어야 합니다.
원본 파일 저장소
업로드된 문서를 로컬 디스크나 객체 스토리지에 보관합니다.
비동기 인덱싱 작업
파일 업로드 후 백그라운드 작업으로 페이지 변환과 임베딩 생성을 처리합니다.
벡터 데이터베이스
소규모 서비스는 FAISS, 다중 사용자 서비스는 Qdrant와 같은 벡터 데이터베이스를 검토할 수 있습니다.
검색 API
사용자 질문을 받아 관련 페이지와 이미지 영역을 반환합니다.
답변 생성 모델
검색된 페이지 이미지를 읽고 질문에 맞는 답변을 생성합니다.
출처 표시 기능
답변과 함께 문서명, 페이지 번호, 원본 페이지 이미지를 표시합니다.

8. 적합한 활용 사례

PixelRAG는 다음과 같은 서비스에 활용할 수 있습니다.

교육 자료 검색

교재의 그림, 문법표, 수학 도형, 과학 실험 이미지가 포함된 페이지를 검색할 수 있습니다.

보고서 분석

매출 그래프, 통계표, 조직도, 비교 차트가 포함된 페이지를 찾아 분석할 수 있습니다.

기술 문서 검색

시스템 구성도, 네트워크 다이어그램, UI 화면, 설치 절차가 포함된 페이지를 검색할 수 있습니다.

스캔 문서 검색

텍스트 추출 품질이 낮은 스캔 문서를 페이지 이미지 상태로 검색할 수 있습니다.

웹페이지 UI 검색

웹페이지를 화면 이미지로 수집한 뒤 특정 메뉴, 버튼, 카드 또는 화면 구성을 검색하는 데 사용할 수 있습니다.

9. 고려해야 할 사항

PixelRAG를 실제 서비스에 적용할 때는 다음 항목을 함께 검토해야 합니다.

문서별 인덱싱 시간
페이지 이미지 저장 공간
GPU 또는 Apple Silicon 사용 여부
임베딩 모델의 메모리 요구량
여러 사용자의 인덱스 분리 방식
질문별 검색 결과 수
비전 언어 모델 호출 비용
답변에 표시할 페이지 출처
문서 삭제 시 이미지와 인덱스를 함께 제거하는 절차
표와 차트의 수치 정확성 검증

특히 이미지 기반 답변은 검색된 페이지의 내용을 비전 모델이 다시 해석하는 구조이므로, 중요한 수치나 표 데이터는 원본 페이지와 함께 제공하는 것이 좋습니다.

10. 결론

PixelRAG는 PDF나 이미지를 OCR 텍스트로 변환해 검색하는 프로젝트가 아닙니다. 문서의 페이지와 화면 영역을 이미지 상태로 임베딩하고, 사용자 질문과 관련된 시각 자료를 검색하는 프로젝트입니다.

따라서 다음과 같이 이해할 수 있습니다.

PixelRAG는 PDF·이미지·웹페이지의 시각적 구조를 유지하면서, 질문과 관련된 페이지나 이미지 영역을 찾아주는 픽셀 기반 검색 시스템이다.

표, 차트, 교재, 인포그래픽, 시스템 구성도처럼 텍스트만 추출하면 정보 구조가 손실되는 문서에서 특히 활용 가치가 있습니다.

다만 완성형 문서 채팅 서비스를 구축하려면 PixelRAG에 파일 업로드 UI, 문서 저장소, 인덱싱 작업 관리, 비전 언어 모델, 답변 생성 및 출처 표시 기능을 추가해야 합니다.

참고 자료

LLM 추론 엔지니어링 튜토리얼

행복한 수지아빠 — Wed, 29 Jul 2026 14:35:33 +0900

LLM 추론 엔지니어링 튜토리얼

이미 만들어진 AI 모델을 GPU 서버에 올리고, 수많은 사용자에게 빠르고 안정적으로 제공하면서 비용까지 최적화하는 기술을 배우는 것입니다.

과정을 마치면 다음 결과물을 갖게 된다.

vLLM과 SGLang으로 구축한 OpenAI 호환 추론 서버
처리량 중심, 지연시간 중심, 긴 문맥 중심의 서빙 파이프라인 3종
비용·지연시간·품질을 함께 고려하는 모델 라우터
사용자별 토큰 예산 및 요청 제어 API
Prometheus·Grafana 기반 운영 대시보드
Kubernetes 자동 확장 환경
1,000개 이상의 동시 요청을 재현하는 부하 시험
재현 가능한 공개 벤치마크 보고서
요청당 원가와 손익분기점을 계산하는 비용 모델

대상 독자

Python과 REST API의 기본 개념을 아는 개발자
로컬 LLM 실행에서 실제 서비스 운영으로 넘어가려는 사람
모델 연구보다 서빙·성능·비용 최적화에 관심이 있는 사람

권장 학습 기간

주 5일, 하루 1.5

~~2시간을 기준으로 12주를 권장한다. GPU가 한 대여도 1~~

8주차 대부분을 학습할 수 있다. 1,000 동시 요청과 Kubernetes 다중 GPU 실습은 클라우드 GPU를 짧게 빌려 수행해도 된다.

전체 학습 지도

단계	기간	핵심 주제	대표 결과물
0	2일	환경과 측정 기준	기준 성능표
1	1주	Ollama·LM Studio·LiteLLM	로컬 API 게이트웨이
2	2주	vLLM·SGLang	서빙 파이프라인 2종
3	1주	Paged Attention·KV 캐시	긴 문맥 서버
4	1주	양자화	정밀도별 비교표
5	1주	추측 디코딩	draft/target 비교 실험
6	1주	라우터·토큰 예산	정책 기반 라우터
7	1주	관측 가능성	Grafana 대시보드
8	1주	부하 시험	1,000 동시 요청 보고서
9	1주	Kubernetes·HPA	자동 확장 배포
10	1주	ONNX·TensorRT·WebLLM	엣지 데모
11	1주	비용 경제성·공개 벤치마크	최종 포트폴리오

0. 준비와 기준선

0.1 권장 환경

로컬 학습용

Ubuntu 22.04/24.04 또는 WSL2
Python 3.11 또는 프로젝트가 지원하는 버전
Docker와 Docker Compose
RAM 64GB 권장, 최소 32GB
SSD 여유 공간 200GB 이상 권장
NVIDIA GPU 24GB 이상 권장

AMD 32GB GPU도 개념 학습, Ollama, llama.cpp 계열, 일부 SGLang·ROCm 실험에 사용할 수 있다. 다만 CUDA 전용 커널, TensorRT-LLM, FP8 및 일부 양자화 경로는 동일하게 재현되지 않을 수 있다. 따라서 이 과정에서는 AMD로 가능한 실습과 CUDA 환경에서 별도로 확인할 실습을 구분한다.

클라우드 실습용

단일 GPU: L4, L40S, A100, H100급 중 예산에 맞는 인스턴스
다중 GPU: 마지막 2주에만 시간 단위로 대여
Kubernetes: 로컬 kind/k3d로 구조를 익힌 뒤 GPU 노드에서 검증

0.2 저장소 구조

llm-inference-lab/
├── README.md
├── models/
├── configs/
├── servers/
│   ├── vllm/
│   ├── sglang/
│   └── router/
├── loadtest/
├── observability/
│   ├── prometheus/
│   └── grafana/
├── kubernetes/
├── edge/
├── results/
└── reports/

0.3 가장 먼저 정의할 지표

지표	의미	주의점
TTFT	요청부터 첫 토큰까지 걸린 시간	대화형 UX에 중요
ITL	토큰 사이의 평균 지연시간	스트리밍 체감 속도
TPOT	출력 토큰 1개당 처리시간	ITL과 정의를 통일
E2E latency	요청 전체 완료 시간	입력·출력 길이를 함께 기록
Throughput	초당 처리한 요청 또는 토큰	요청/초와 토큰/초를 구분
Goodput	SLO를 만족한 유효 처리량	단순 처리량보다 운영에 유용
Queue time	대기열에서 기다린 시간	GPU 계산 시간과 분리
Cache hit rate	재사용된 prefix/KV 비율	동일 프롬프트 비율과 함께 기록
Error rate	전체 요청 중 실패 비율	타임아웃과 서버 오류를 구분
Cost/request	요청 한 건의 추론 원가	GPU 유휴시간도 포함

0.4 기준선 실험

동일한 모델, 동일한 데이터셋, 동일한 입력·출력 길이로 아래 표를 채운다.

| 엔진 | 모델 | 정밀도 | 동시성 | 입력/출력 토큰 | TTFT p50/p95 | ITL p50/p95 | tok/s | GPU 메모리 |
|---|---|---|---:|---:|---:|---:|---:|---:|

완료 조건

측정 스크립트를 두 번 실행해 결과 편차를 확인했다.
모델명, revision, 엔진 버전, GPU, 드라이버를 기록했다.
워밍업 요청을 측정값에서 분리했다.

1. 로컬 도구로 추론 흐름 익히기

1.1 Ollama

학습 목표는 모델 다운로드, 메모리 적재, 프롬프트 요청, 스트리밍 응답의 흐름을 이해하는 것이다.

ollama pull qwen3:4b
ollama run qwen3:4b

API 확인:

curl http://localhost:11434/api/generate \
  -d '{"model":"qwen3:4b","prompt":"KV cache를 한 문장으로 설명해 줘.","stream":false}'

확인할 항목:

첫 요청과 두 번째 요청의 시간 차이
모델이 메모리에 남아 있을 때의 변화
입력 길이가 늘어날 때 TTFT 변화

1.2 LM Studio

GUI에서 모델별 메모리 사용량과 오프로딩 설정을 비교한다. 로컬 서버 기능을 켠 뒤 OpenAI 호환 클라이언트로 호출한다.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:1234/v1", api_key="local")
response = client.chat.completions.create(
    model="local-model",
    messages=[{"role": "user", "content": "continuous batching을 설명해 줘."}],
)
print(response.choices[0].message.content)

1.3 LiteLLM

LiteLLM은 여러 모델 제공자 또는 로컬 서버를 하나의 API 형태로 연결하는 게이트웨이 실습에 사용한다.

# configs/litellm.yaml
model_list:
  - model_name: local-fast
    litellm_params:
      model: openai/local-model
      api_base: http://localhost:1234/v1
      api_key: local

litellm --config configs/litellm.yaml

미니 프로젝트

Ollama와 LM Studio 중 사용 가능한 서버를 선택하고, 실패하면 다른 서버로 전환하는 작은 게이트웨이를 만든다.

완료 조건

/v1/chat/completions로 두 개 이상의 백엔드에 요청했다.
모델 로딩 시간과 순수 생성 시간을 분리했다.
타임아웃과 연결 실패를 로그에서 구분했다.

2. vLLM과 SGLang

아래 명령의 옵션은 릴리스에 따라 달라질 수 있다. 실습 전에 각 프로젝트의 공식 최신 CLI 문서를 확인한다.

2.1 vLLM 서버

별도의 가상환경에서 설치한다.

python -m venv .venv-vllm
source .venv-vllm/bin/activate
python -m pip install --upgrade pip
pip install vllm

서버 시작:

vllm serve Qwen/Qwen3-4B-Instruct-2507 \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype auto \
  --api-key local-token

요청:

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer local-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"Qwen/Qwen3-4B-Instruct-2507",
    "messages":[{"role":"user","content":"Paged Attention이 필요한 이유는?"}],
    "max_tokens":128
  }'

검증:

curl http://localhost:8000/health
curl http://localhost:8000/metrics

2.2 SGLang 서버

python -m venv .venv-sglang
source .venv-sglang/bin/activate
python -m pip install --upgrade pip
pip install "sglang[all]"

python -m sglang.launch_server \
  --model-path Qwen/Qwen3-4B-Instruct-2507 \
  --host 0.0.0.0 \
  --port 30000

같은 프롬프트 묶음을 vLLM과 SGLang에 보내 다음을 비교한다.

단일 요청 TTFT
동시성 1, 8, 32, 128의 처리량
반복 prefix가 있을 때의 처리량
긴 입력과 짧은 출력
짧은 입력과 긴 출력

2.3 파이프라인 3종

A. 처리량 우선

연속 배칭 활성화
GPU 메모리 사용률을 점진적으로 높여 탐색
동시 요청 수를 늘리며 최대 goodput 측정
p95 지연시간 SLO를 넘으면 직전 설정으로 복귀

B. 대화형 지연시간 우선

요청당 출력 상한 설정
대형 배치보다 짧은 대기열 선호
스트리밍 사용
TTFT p95를 핵심 SLO로 설정

C. 긴 문맥 우선

prefix caching 또는 Radix Cache 활용
최대 문맥 길이를 실제 제품 요구에 맞춰 제한
KV 캐시 부족 시 선점·재계산·퇴출 현상 관찰
긴 요청이 짧은 요청을 막지 않도록 스케줄링 정책 실험

완료 조건

두 엔진의 결과를 같은 표 형식으로 기록했다.
“어느 엔진이 항상 빠르다”가 아니라 워크로드별 승자를 설명했다.
서버 시작 명령과 전체 환경 정보를 보고서에 남겼다.

3. Paged Attention과 KV 캐시

3.1 먼저 이해할 계산

Transformer의 KV 캐시 메모리는 모델 구조와 데이터형에 따라 달라진다. 개념적으로는 다음 항목에 비례한다.

KV cache bytes
≈ batch × sequence_length × layers
  × 2(K,V) × KV_heads × head_dim × bytes_per_element

Grouped Query Attention을 사용하는 모델은 attention head 수 대신 KV head 수가 중요하다. 모델 설정 파일의 num_key_value_heads, num_hidden_layers, head_dim 또는 이에 해당하는 값을 직접 확인한다.

3.2 Paged Attention

Paged Attention은 요청별 KV 캐시를 고정된 큰 연속 공간으로 잡는 대신 블록 단위로 관리해 단편화와 낭비를 줄이는 접근이다. 운영 관점에서는 다음 질문으로 연결한다.

블록 크기가 메모리 낭비와 관리 비용에 어떤 영향을 주는가?
요청이 끝난 뒤 블록이 얼마나 빨리 재사용되는가?
여러 요청이 동일 prefix를 공유할 때 어느 정도 절약되는가?

3.3 캐시 퇴출 실험

세 가지 트래픽을 만든다.

짧은 대화 100개
동일한 시스템 프롬프트를 공유하는 요청 100개
긴 문서 질의 20개와 짧은 대화 100개의 혼합

각 실험에서 다음을 기록한다.

KV 캐시 사용률
prefix cache hit rate
preemption 또는 recomputation 횟수
대기열 길이
TTFT p50/p95/p99

3.4 퇴출 정책 설계 과제

아래 점수로 직접 정책을 설계한다.

eviction_score =
  0.40 × idle_time_normalized
  + 0.25 × cache_size_normalized
  + 0.20 × recompute_cost_inverse
  + 0.15 × tenant_priority_inverse

이 공식은 학습용 예시다. 가중치를 바꾸며 다음 사례를 비교한다.

LRU
가장 큰 캐시 우선
재계산 비용이 낮은 항목 우선
유료 사용자 우선 보존

완료 조건

캐시가 부족해지는 시점을 그래프로 찾았다.
hit rate가 높아져도 p95가 나빠질 수 있는 조건을 설명했다.
퇴출 정책의 장단점을 실제 측정값으로 비교했다.

4. 양자화: INT4, FP8, AWQ, GPTQ

4.1 구분

방식	핵심 성격	주로 확인할 것
FP8	낮은 정밀도의 부동소수점 연산	하드웨어 지원, 처리량, 품질
INT4	4비트 정수 기반 가중치 표현	메모리 절감, 커널 지원
AWQ	activation을 고려한 weight-only 양자화	실제 프롬프트 품질
GPTQ	2차 정보 근사를 이용한 사후 학습 양자화	양자화 설정과 커널 호환성

AWQ와 GPTQ는 “파일이 더 작다”만으로 평가하지 않는다. 엔진과 GPU에 맞는 커널이 없으면 메모리는 줄어도 속도가 느려질 수 있다.

4.2 비교 실험

동일 모델 계열에서 BF16/FP16, FP8, AWQ INT4, GPTQ INT4를 준비한다.

| 형식 | 모델 크기 | VRAM idle/peak | TTFT p95 | tok/s | 정확도 | 비고 |
|---|---:|---:|---:|---:|---:|---|

품질 평가는 최소 세 층으로 나눈다.

짧은 지식·상식 100문항
한국어 지시 이행 50문항
실제 서비스 프롬프트 50개

4.3 선택 규칙

if GPU가 FP8을 효율적으로 지원하고 품질 저하가 허용 범위:
    FP8 후보
elif VRAM이 가장 큰 제약이고 지원 커널이 검증됨:
    AWQ 또는 GPTQ INT4 후보
else:
    BF16/FP16 기준선 유지

완료 조건

메모리 절감률과 처리량 향상률을 따로 기록했다.
정확도 평균뿐 아니라 실패 유형을 분류했다.
현재 장비에서 실제로 지원하지 않는 경로를 미검증으로 표시했다.

5. 추측 디코딩

5.1 개념

작은 draft 모델이 여러 후보 토큰을 먼저 제안하고 target 모델이 이를 검증한다. 목표는 출력 품질을 유지하면서 토큰 사이 지연시간을 낮추는 것이다. 성능 향상은 모델 조합, acceptance rate, 배치 크기, 메모리 대역폭과 워크로드에 따라 달라진다.

5.2 실험 설계

변수	값 예시
target model	7B~14B instruct
draft model	같은 tokenizer를 쓰는 소형 모델
speculative tokens	1, 3, 5, 8
동시성	1, 8, 32
출력 길이	32, 256, 1,024

수집 항목:

draft acceptance rate
speculative efficiency
ITL p50/p95
전체 처리량
추가 GPU 메모리
비추측 기준선 대비 속도 변화

5.3 중단 조건

다음 중 하나면 해당 설정을 채택하지 않는다.

p95 ITL이 기준선보다 나빠짐
draft 모델 메모리 때문에 동시성이 감소함
acceptance rate가 낮아 추가 계산이 이익을 상쇄함

완료 조건

최소 2개 draft/target 조합을 비교했다.
단일 요청과 높은 동시성에서 결과가 다른 이유를 설명했다.

6. 모델 라우터와 토큰 예산

6.1 라우팅 목표

라우터는 “가장 좋은 모델”을 고르는 장치가 아니라 요청의 품질 하한, 지연시간 SLO, 비용 상한을 동시에 만족하는 후보를 선택하는 정책 계층이다.

flowchart TD
    A["사용자 요청"] --> B["정책·예산 검사"]
    B --> C["난이도·길이 분류"]
    C --> D{"후보 모델"}
    D --> E["저비용 모델"]
    D --> F["저지연 모델"]
    D --> G["고품질 모델"]
    E --> H["응답·비용 기록"]
    F --> H
    G --> H

6.2 최소 데이터 모델

from dataclasses import dataclass

@dataclass
class ModelProfile:
    name: str
    input_cost_per_million: float
    output_cost_per_million: float
    p95_ttft_ms: float
    p95_itl_ms: float
    quality_score: float
    max_context: int

6.3 점수 함수

def route_score(
    quality: float,
    latency_ms: float,
    estimated_cost: float,
    quality_weight: float = 0.5,
    latency_weight: float = 0.3,
    cost_weight: float = 0.2,
) -> float:
    return (
        quality_weight * quality
        - latency_weight * latency_ms
        - cost_weight * estimated_cost
    )

실제 구현에서는 단위가 다른 값을 그대로 더하지 말고 0~1 범위로 정규화한다. 또한 품질 하한과 비용 상한을 먼저 적용한 후 남은 후보에 점수를 계산한다.

6.4 토큰 예산

def output_budget(
    plan_limit: int,
    used_tokens: int,
    requested_max_tokens: int,
    reserve_tokens: int = 256,
) -> int:
    remaining = max(0, plan_limit - used_tokens - reserve_tokens)
    return min(requested_max_tokens, remaining)

필수 정책:

사용자·팀·API 키별 일/월 토큰 한도
요청당 최대 입력·출력 토큰
시스템 프롬프트와 도구 호출 토큰 포함 여부
스트리밍 도중 예산 소진 처리
재시도와 fallback 요청의 중복 과금 처리
예약량과 실제 사용량의 정산

6.5 라우터 평가

정적 규칙, latency 기반, cost 기반, 품질 포함 다목적 라우터를 같은 요청 집합으로 비교한다.

| 정책 | 성공률 | 품질 | p95 지연 | 평균 원가 | SLO 위반률 |
|---|---:|---:|---:|---:|---:|

완료 조건

라우팅 이유를 요청 로그에서 재현할 수 있다.
예산 초과 요청은 GPU에 도달하기 전에 거절된다.
fallback이 무한 반복되지 않는다.

7. 관측 가능성: Prometheus와 Grafana

7.1 반드시 수집할 네 종류

요청

요청 수, 성공 수, 오류 수
입력·출력 토큰
모델, tenant, 상태 코드

지연시간

TTFT
ITL/TPOT
E2E
queue time

엔진

실행 중·대기 중 요청
KV 캐시 사용률과 hit rate
preemption
batch 크기

자원

GPU 사용률, 메모리, 전력
CPU, RAM, 네트워크
Pod 재시작과 OOM

7.2 카디널리티 경고

Prometheus label에 user_id, request_id, 전체 프롬프트를 넣지 않는다. 사용자 단위 상세 기록은 로그 또는 분석 저장소에 보내고, 메트릭은 plan, model, region처럼 제한된 값만 사용한다.

7.3 대시보드 구성

서비스 건강: RPS, error rate, p95 E2E
사용자 경험: TTFT와 ITL
GPU 효율: utilization, memory, tokens/s
스케줄러: running/waiting requests, queue time
캐시: KV 사용률, prefix hit rate, preemption
비용: 시간당 비용, 요청당 비용, 1M token당 비용

7.4 알림 예시

groups:
  - name: llm-serving
    rules:
      - alert: LLMHighErrorRate
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m]))
          /
          clamp_min(sum(rate(http_requests_total[5m])), 1)
          > 0.02
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "LLM API 5xx 비율이 2%를 초과했습니다."

메트릭 이름은 실제 애플리케이션에서 노출하는 이름에 맞춰 수정한다.

완료 조건

느린 응답이 queue, prefill, decode 중 어디서 발생했는지 구분한다.
대시보드의 수치와 원시 요청 로그를 표본 대조했다.

8. 1,000+ 동시 요청 부하 시험

8.1 도구

k6: HTTP 부하와 시나리오 작성
Locust: Python 기반 사용자 행동 모델
vegeta: 단순 HTTP 처리량 확인
엔진별 benchmark 도구: 순수 추론 성능 확인

OpenAI 스트리밍 응답은 일반 HTTP 완료 시간만 측정하면 TTFT와 ITL을 놓칠 수 있다. SSE 청크의 도착 시간을 기록하는 전용 클라이언트를 준비한다.

8.2 단계적 증가

1 → 8 → 32 → 64 → 128 → 256 → 512 → 1,000 → 1,500

각 단계에서 최소 5분간 안정 상태를 측정한다. 오류율 또는 p95가 SLO를 넘으면 더 높은 단계로 진행하지 않고 원인을 찾는다.

8.3 현실적인 요청 분포

유형	비율	입력 토큰	출력 토큰
짧은 질의	50%	64~256	32~128
일반 대화	30%	256~1,024	128~512
긴 문서	15%	4K~16K	128~512
긴 생성	5%	256~1K	1K~4K

8.4 보고서

동시성별 offered load와 completed throughput
p50/p95/p99 TTFT, ITL, E2E
timeout, 429, 5xx
GPU 사용률과 메모리
queue length
SLO를 만족하는 최대 goodput

완료 조건

1,000 연결을 열었다는 사실과 1,000 요청이 성공했다는 사실을 구분했다.
클라이언트 CPU·네트워크가 병목이 아닌지 확인했다.
실패 지점과 안전 운영 한계를 명시했다.

9. Kubernetes와 GPU 자동 확장

9.1 학습 순서

Deployment와 Service
GPU resource request
readiness/liveness probe
rolling update
node selector, taint, toleration
HPA
Prometheus custom metrics
queue 기반 확장

9.2 Deployment 골격

apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: llm-server
  template:
    metadata:
      labels:
        app: llm-server
    spec:
      containers:
        - name: server
          image: your-registry/llm-server:VERSION
          ports:
            - containerPort: 8000
          resources:
            limits:
              nvidia.com/gpu: 1
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 60
            periodSeconds: 10

이미지 태그와 health endpoint는 실제 배포물에 맞춰 검증한다.

9.3 HPA 골격

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: llm-server
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: llm-server
  minReplicas: 1
  maxReplicas: 8
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 600
  metrics:
    - type: Pods
      pods:
        metric:
          name: llm_waiting_requests
        target:
          type: AverageValue
          averageValue: "4"

이 예시는 custom metrics adapter가 llm_waiting_requests를 제공한다고 가정한다. GPU Pod는 모델 로딩 시간이 길기 때문에 CPU 사용률만으로 확장하면 늦을 수 있다. queue length, waiting requests, 예상 대기시간 같은 선행 지표를 비교한다.

9.4 운영 실험

0→100 요청 급증
10분 동안 점진 증가
한 Pod 강제 종료
새 모델 이미지 rolling update
노드 하나 장애

완료 조건

새 Pod가 준비되기 전에는 트래픽을 받지 않는다.
scale-down 중 진행 중 요청의 종료 정책을 검증했다.
모델 다운로드 시간이 확장 지연에 포함됨을 측정했다.

10. 엣지 배포

10.1 ONNX Runtime

작은 encoder 또는 소형 생성 모델을 ONNX로 변환해 CPU, DirectML, CUDA 실행 공급자를 비교한다.

학습 항목:

정적 shape와 동적 shape
graph optimization
INT8 양자화
cold start와 warm latency

10.2 TensorRT 계열

CUDA 환경에서만 별도 트랙으로 진행한다.

엔진 빌드 시간과 실행 시간 구분
지원 precision 확인
고정/동적 shape profile
GPU 아키텍처와 엔진 호환성

AMD 장비에서는 이 트랙을 개념 학습 후 클라우드 NVIDIA GPU에서 검증한다.

10.3 WebLLM

브라우저에서 WebGPU로 소형 모델을 실행한다.

측정 항목:

최초 모델 다운로드 크기와 시간
브라우저별 WebGPU 지원
prefill/decode 속도
탭 전환과 메모리 회수
개인정보가 서버로 전송되지 않는 로컬 처리 범위

10.4 엣지 의사결정표

조건	후보
브라우저 오프라인 실행	WebLLM
데스크톱/모바일 네이티브	ONNX Runtime
NVIDIA 서버 최대 성능	TensorRT 계열
개발 편의와 폭넓은 모델	llama.cpp/Ollama 계열

완료 조건

같은 작은 모델을 서버와 엣지에서 비교했다.
다운로드 비용, cold start, 전력, 개인정보를 성능표에 포함했다.

11. 추론 비용과 단위 경제성

11.1 기본 공식

GPU hourly cost
= 인스턴스 비용 + 스토리지 + 네트워크 + 관측 비용

effective tokens per hour
= measured tokens/s × 3,600 × utilization × success_rate

cost per 1M tokens
= GPU hourly cost / effective tokens per hour × 1,000,000

cost per request
= input_token_cost + output_token_cost
  + routing + storage + network + retry overhead

11.2 손익분기점

gross margin per request
= revenue per request - variable cost per request

break-even requests per month
= monthly fixed cost / gross margin per request

11.3 반드시 포함할 숨은 비용

낮은 사용률과 유휴 GPU
모델 로딩과 재배포 시간
실패·재시도·fallback
긴 system prompt
사용하지 않고 남은 예약 용량
로그·메트릭·네트워크
엔지니어 운영 시간
품질 저하로 발생하는 재질문

11.4 실습

세 시나리오를 비교한다.

단일 고성능 GPU 자체 서빙
여러 저가 GPU 자체 서빙
외부 API 사용

트래픽이 낮음/보통/높음일 때 월 비용과 gross margin을 계산한다. 자체 서빙은 최고 처리량이 아니라 실제 평균 사용률로 계산한다.

완료 조건

가격과 성능 수치의 기준일을 기록했다.
최선/기준/최악 시나리오를 분리했다.
비용 절감이 품질과 SLO에 미치는 영향을 함께 제시했다.

12. 최종 프로젝트

프로젝트 요구사항

다음 아키텍처를 구현한다.

flowchart TD
    A["클라이언트"] --> B["API·토큰 예산"]
    B --> C["모델 라우터"]
    C --> D["vLLM 풀"]
    C --> E["SGLang 풀"]
    D --> F["Prometheus"]
    E --> F
    F --> G["Grafana"]

기능

OpenAI 호환 chat completions API
최소 2개 모델 또는 2개 배포
비용·지연시간·품질 기반 라우팅
사용자별 일일 토큰 예산
스트리밍
요청·토큰·오류·비용 기록
Prometheus 메트릭
Grafana 대시보드
부하 시험
Docker Compose 로컬 실행
선택: Kubernetes와 HPA

서빙 파이프라인

처리량 최적화 vLLM
prefix 공유에 최적화한 SGLang
양자화 또는 추측 디코딩을 적용한 실험 파이프라인

공개 벤치마크 필수 정보

date:
git_commit:
model_id:
model_revision:
engine:
engine_version:
container_image:
gpu:
gpu_count:
driver:
cuda_or_rocm:
cpu:
ram:
prompt_dataset:
input_length_distribution:
output_length_distribution:
concurrency:
warmup:
duration:
sampling_parameters:

최종 평가표

영역	배점	통과 기준
재현성	20	다른 사람이 명령대로 실행 가능
성능 측정	20	TTFT·ITL·goodput·오류 포함
캐시·배칭	15	적용 전후 비교
라우팅·예산	15	결정 이유와 제한 동작 확인
관측	10	병목 위치를 대시보드에서 확인
부하 시험	10	현실적인 분포와 안전 중단
비용	10	요청당 원가와 손익분기점

매일 공부 루틴

90분 버전

15분: 공식 문서 또는 논문 한 절 읽기
45분: 하나의 변수만 바꾸는 실험
15분: 그래프와 표 업데이트
10분: 실패 원인 기록
5분: 다음 실험의 가설 작성

실험 노트 양식

# 실험 제목

## 가설

## 고정 조건

## 변경 변수

## 실행 명령

## 예상 결과

## 실제 결과

## 해석

## 미검증 항목

## 다음 실험

논문과 자료를 읽는 법

모델 출시 뉴스보다 다음 질문에 답하는 자료를 우선한다.

메모리 이동량을 어떻게 줄였는가?
prefill과 decode를 어떻게 나눴는가?
배칭과 스케줄링이 tail latency에 어떤 영향을 주는가?
KV 캐시를 어떻게 배치·압축·퇴출하는가?
품질을 유지하면서 연산량을 어떻게 줄였는가?
어떤 하드웨어와 워크로드에서만 이득이 있었는가?

읽을 주제:

PagedAttention
continuous batching
prefix caching와 RadixAttention
speculative decoding, Medusa, EAGLE 계열
disaggregated prefill/decode
KV cache quantization과 eviction
tensor/pipeline/data/expert parallelism
goodput과 SLO-aware scheduling

논문 요약에는 반드시 기준선, 하드웨어, 모델, 입력·출력 길이, 동시성, 한계를 기록한다.

자주 발생하는 실패

CUDA/ROCm 메모리 부족

확인 순서:

다른 프로세스가 GPU 메모리를 쓰는지 확인
최대 문맥 길이와 동시 요청 수 축소
GPU memory utilization 설정 점검
양자화 모델로 기준선 재구성
CPU offload는 속도 저하를 포함해 다시 측정

처리량은 높은데 응답이 느림

[Inference] 높은 배치 크기로 총 처리량은 올라갔지만 queue time 또는 TTFT가 악화됐을 가능성이 있다. 대기시간과 실제 GPU 실행 시간을 분리해 확인한다.

GPU 사용률이 낮음

[Inference] 입력 준비, 토크나이징, 네트워크, 작은 배치 또는 부하 생성기가 병목일 가능성이 있다. GPU만 보지 말고 CPU, queue, batch size, 클라이언트 사용률을 함께 확인한다.

양자화했는데 느려짐

[Inference] 현재 GPU·엔진에 최적화된 커널이 없거나 dequantization 비용이 이득을 상쇄했을 가능성이 있다. 동일 동시성과 동일 길이에서 커널 및 정밀도별 결과를 비교한다.

HPA가 늦게 확장됨

[Inference] CPU 사용률이 대기열 증가보다 늦게 반응하거나 모델 로딩 시간이 긴 것이 원인일 수 있다. waiting requests와 예상 대기시간을 선행 지표 후보로 검증한다.

공식 문서

시작 체크리스트

GPU와 드라이버 정보를 기록했다.
모델과 엔진 버전을 고정했다.
TTFT, ITL, throughput, goodput 정의를 정했다.
Ollama 또는 LM Studio API를 호출했다.
vLLM 서버를 실행했다.
SGLang 서버를 실행했다.
동일 워크로드로 두 엔진을 비교했다.
KV 캐시 사용률과 cache hit rate를 관찰했다.
양자화 전후 메모리·속도·품질을 비교했다.
추측 디코딩의 acceptance rate를 측정했다.
모델 라우터와 토큰 예산을 구현했다.
Prometheus와 Grafana를 연결했다.
1,000 동시 요청 시험을 수행했다.
Kubernetes HPA를 검증했다.
요청당 원가와 손익분기점을 계산했다.
모든 명령과 환경을 공개 보고서에 기록했다.

검증 범위와 주의사항

이 문서는 학습 사이트의 구조와 실습 설계를 제공한다. 이 환경에는 GPU가 연결되어 있지 않아 vLLM, SGLang, CUDA, ROCm, Kubernetes GPU 배포 명령을 실제 실행하지 않았다. 따라서 각 실습의 성공 결과는 미검증이며, 사용하는 GPU·드라이버·엔진 릴리스의 공식 문서에서 지원 조합과 CLI 옵션을 확인해야 한다.

Unity CLI 에 대해 알아보자

행복한 수지아빠 — Wed, 29 Jul 2026 09:22:50 +0900

1. Unity CLI란?

Unity CLI는 Unity Hub 화면을 열지 않고 터미널에서 Unity 개발환경을 관리하는 공식 명령줄 도구입니다.

주요 역할은 다음과 같습니다.

Unity Editor 설치
Android·iOS·WebGL 모듈 설치
설치된 Editor 목록 확인
프로젝트에 맞는 Unity 버전으로 실행
Unity 계정 로그인
CLI 업데이트
CI/CD 환경 자동 구성

기존 Unity Hub의 CLI 기능과 달리, 독립된 unity 네이티브 실행 파일로 제공되므로 CI 서버나 AI 에이전트가 호출하기에 적합합니다.

현재 글 작성 시점 기준으로 Unity CLI와 Unity Pipeline 모두 experimental 단계입니다.

2. 설치

macOS / Linux

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh \
  | UNITY_CLI_CHANNEL=beta bash

Windows PowerShell

$env:UNITY_CLI_CHANNEL='beta'
irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

설치 후 터미널을 다시 열고 확인합니다.

unity --version

3. Unity Editor 설치

특정 버전 설치

unity install 6000.3.7f1

플랫폼 모듈과 함께 설치

unity install lts -m android ios webgl

기존 Editor에 모듈 추가

unity install-modules -e 6000.3.7f1 -m android ios

주의할 점은 모듈 추가가 가능한 Editor가 다음 방식으로 설치된 경우에 한정된다는 것입니다.

Unity Hub로 설치
Unity CLI로 설치

수동으로 복사하거나 직접 배치한 Editor는 모듈 추가 대상이 아닐 수 있습니다.

4. Unity 프로젝트 실행

unity open ./MyProject

open은 생략할 수도 있습니다.

unity ./MyProject

Unity CLI가 프로젝트의 설정을 읽고 해당 프로젝트에 필요한 Unity Editor 버전을 찾아 실행합니다.

즉, 프로젝트마다 Unity 버전이 다를 때 직접 Editor 실행 경로를 지정하는 작업을 줄일 수 있습니다.

5. 인증과 업데이트

Unity 계정 로그인

unity auth login

로그인 상태 확인

unity auth status

Unity CLI 업데이트

unity upgrade

헤드리스 서버나 CI 환경에서는 환경변수를 이용한 서비스 계정 인증도 지원하는 구조입니다.

6. CI/CD 활용

Unity CLI는 자동화 도구가 결과를 읽기 쉽도록 구조화된 출력 형식을 지원합니다.

JSON 출력

unity editors --format json

TSV 출력

unity editors --format tsv

표준 출력과 오류 출력이 분리되고 종료 코드도 명확합니다.

종료 코드의미

0	성공
1	오류
130	사용자 또는 작업 취소

확인 질문 없이 자동 설치할 수도 있습니다.

unity install lts \
  -m android ios \
  --accept-eula \
  --yes

환경이나 인증 문제를 진단할 때는 다음 명령을 사용합니다.

unity doctor

GitHub Actions 같은 CI에서는 다음 작업을 자동화할 수 있습니다.

저장소 체크아웃
→ Unity CLI 설치
→ 지정 Unity 버전 설치
→ 플랫폼 모듈 설치
→ 인증
→ 테스트
→ 빌드
→ 결과 및 종료 코드 확인

7. Unity CLI와 Unity Pipeline의 차이

두 도구의 역할을 구분하는 것이 중요합니다.

구분Unity CLIUnity Pipeline

주요 목적	Unity 설치 및 실행환경 관리	실행 중인 Editor·Player 외부 제어
Editor 설치	가능	담당하지 않음
모듈 설치	가능	담당하지 않음
프로젝트 실행	가능	실행 후 내부 조작
Play 모드 제어	Pipeline을 통해 가능	가능
Unity API 호출	직접적인 핵심 기능 아님	가능
C# 코드 실행	직접적인 핵심 기능 아님	eval 지원
AI 에이전트 연동	환경 관리 담당	실제 Editor 조작 담당

정리하면 다음과 같습니다.

Unity CLI
= Unity 개발환경을 설치하고 프로젝트를 실행하는 도구

Unity Pipeline
= 실행 중인 Unity Editor와 Player를 외부에서 조작하는 도구

8. Unity Pipeline 설치

프로젝트를 실행한 상태에서 다음 명령으로 Pipeline 패키지를 추가합니다.

unity pipeline install

Unity Pipeline은 제공된 글 기준으로 Unity 6.0 LTS 이상을 대상으로 하며, 로컬 API를 통해 Unity CLI와 Editor를 연결합니다.

사용 가능한 명령 목록을 확인합니다.

unity command

특정 명령을 실행합니다.

unity command <command-name>

예를 들면 프로젝트에 등록된 테스트나 에디터 도구를 다음처럼 호출하는 구조입니다.

unity command run-tests
unity command enter-play-mode
unity command generate-assets

단, 실제 명령 이름은 프로젝트에 등록된 명령에 따라 달라집니다.

9. 프로젝트 전용 CLI 명령 만들기

C# 정적 메서드에 CliCommand 속성을 붙이면 프로젝트 전용 명령을 만들 수 있습니다.

using Unity.Pipeline.Commands;
using UnityEngine;

public static class MyPipelineCommands
{
    [CliCommand("greet", "Log a greeting and return its length")]
    public static int Greet(
        [CliArg("name", "Who to greet", Required = true)] string name)
    {
        Debug.Log($"Hello, {name}!");
        return name.Length;
    }
}

터미널에서는 다음처럼 실행합니다.

unity command greet --name World

별도의 복잡한 등록 코드 없이 속성이 붙은 메서드가 자동으로 검색됩니다.

이 방식으로 다음 기능을 CLI 명령으로 공개할 수 있습니다.

씬 생성 및 변경
GameObject 배치
프리팹 생성
에셋 임포트
테스트 실행
프로젝트 검증
빌드
Play 모드 진입
커스텀 에디터 도구 실행

10. Unity Editor 안에서 C# 실행

Unity Pipeline은 실행 중인 Editor 내부에서 C# 표현식이나 코드를 실행하는 eval 기능을 제공합니다.

Unity 버전 확인

unity command eval "return Application.version;"

Play 모드 상태 확인

unity command eval \
  "return UnityEditor.EditorApplication.isPlaying;"

C# 파일 실행

unity command eval_file "path/to/script.cs"

코드는 Roslyn으로 컴파일되어 Unity Editor의 메인 스레드에서 실행됩니다.

장점은 전체 프로젝트를 다시 컴파일하거나 도메인을 리로드하지 않고도 Unity API를 호출할 수 있다는 점입니다.

다만 eval은 임의의 Unity API를 실행할 수 있으므로 보안상 매우 강력한 기능입니다. 제공된 글에 따르면 실행 시 보안 토큰이 필요합니다.

11. 개발용 Player 제어

Unity Pipeline 런타임 컴포넌트를 Development Build에 포함하면 Editor뿐 아니라 실행 중인 게임 Player도 제어할 수 있습니다.

unity command --runtime <player-name>

가능한 활용 사례는 다음과 같습니다.

Player 로그 수집
게임 상태 조회
런타임 API 호출
자동 QA 수행
개발용 Player 코드 핫리로드
특정 위치나 게임 상태 재현
테스트 캐릭터 또는 데이터를 주입

이 기능은 기본적으로 비활성화되어 있고 로컬호스트 접속을 전제로 합니다.

따라서 배포용 본 게임보다는 다음 환경에 적합합니다.

개발용 빌드
내부 QA 빌드
자동 테스트용 빌드
에이전트 검증용 빌드

12. AI 에이전트와의 연동

Unity CLI와 Pipeline이 중요한 이유는 AI가 단순히 C# 코드만 작성하는 수준에서 벗어나 실제로 Unity를 실행하고 결과를 검증할 수 있는 기반을 제공하기 때문입니다.

기존 AI 코딩 흐름은 보통 다음과 같았습니다.

AI가 코드 작성
→ 사람이 Unity Editor 실행
→ 사람이 컴파일 오류 확인
→ 사람이 Play 모드 실행
→ 결과를 다시 AI에게 설명

Unity CLI와 Pipeline을 연결하면 다음 흐름으로 확장할 수 있습니다.

AI가 프로젝트 분석
→ Unity 프로젝트 실행
→ C# 코드 수정
→ Unity 컴파일 상태 확인
→ 테스트 실행
→ Play 모드 진입
→ 로그 및 상태 조회
→ 오류 분석
→ 코드 재수정
→ 다시 테스트

특히 JSON 출력, 공통 종료 코드, 커스텀 CLI 명령이 있기 때문에 AI가 Unity 화면을 이미지로 분석하지 않고도 구조화된 결과를 받을 수 있습니다.

13. MCP와 연결했을 때의 구조

[Inference] 다음 구조는 제공된 기능 설명을 기반으로 정리한 일반적인 연동 방식입니다.

Claude Code / Codex / Gemini CLI / 자체 AI 에이전트
                    ↓
                 MCP 서버
                    ↓
               Unity CLI
                    ↓
             Unity Pipeline
                    ↓
       Unity Editor 또는 Development Player

MCP 도구는 예를 들어 다음 형태로 설계할 수 있습니다.

unity_open_project
unity_get_commands
unity_execute_command
unity_eval
unity_run_tests
unity_enter_play_mode
unity_get_console_logs
unity_build_project
unity_inspect_scene

다만 eval을 AI에게 직접 무제한 공개하는 것은 위험할 수 있으므로, 실무에서는 허용된 작업만 수행하는 커스텀 명령을 만드는 편이 더 안전합니다.

예:

[CliCommand("validate-scene", "Validate the active scene")]
public static ValidationResult ValidateScene()
{
    // 허용된 검증 작업만 수행
}

14. 가장 유용한 실무 활용 사례

자동 개발환경 구성

unity install 6000.3.7f1 -m android --accept-eula --yes
unity auth login
unity ./MyProject

자동 테스트

unity command run-tests

프로젝트 상태 검사

unity command validate-project

AI가 생성한 씬 검증

AI가 씬 생성 코드 작성
→ Unity CLI로 프로젝트 실행
→ Pipeline 명령으로 씬 생성
→ Play 모드 실행
→ 로그 확인
→ 실패 시 재수정

모바일 빌드 자동화

Unity 설치
→ Android 또는 iOS 모듈 설치
→ 프로젝트 열기
→ 테스트
→ 빌드 명령 실행
→ 빌드 산출물 확인

15. 주의할 점

아직 실험 단계

Unity CLI와 Unity Pipeline 모두 experimental이므로 명령 형식이나 API가 변경될 가능성이 있습니다.

eval 보안

eval은 Unity Editor 안에서 임의의 C# 코드를 실행할 수 있습니다. 신뢰할 수 없는 입력이나 외부 네트워크에 직접 노출하면 위험합니다.

Editor 메인 스레드

Pipeline 코드가 Editor 메인 스레드에서 실행되므로 장시간 작업을 동기적으로 실행하면 Editor가 멈춘 것처럼 보일 수 있습니다.

커스텀 명령 우선

AI 연동에서는 자유로운 eval보다 명시적으로 검증된 CliCommand를 제공하는 편이 적절합니다.

권장:
unity command build-android
unity command validate-scene
unity command run-game-tests

주의:
unity command eval "<AI가 생성한 임의 코드>"

개발용 Player에서만 사용

런타임 제어 기능은 배포용 빌드가 아니라 Development Build와 QA 환경 중심으로 사용하는 것이 적합합니다.

핵심 요약

Unity CLI
- Unity Editor 설치
- 플랫폼 모듈 설치
- 프로젝트 실행
- 계정 인증
- CI 환경 구성

Unity Pipeline
- 실행 중인 Editor 제어
- 커스텀 CLI 명령 실행
- C# 코드 실행
- Play 모드와 테스트 제어
- Development Player 제어

두 도구를 결합하면
AI가 Unity 프로젝트를 수정하는 데서 끝나지 않고
실행·테스트·로그 확인·재수정까지 자동화할 수 있다.

가장 중요한 변화는 Unity Hub를 CLI로 대체하는 것 자체가 아니라, Unity Editor를 AI 에이전트가 검증 가능한 형태로 외부 제어할 수 있게 되었다는 점입니다.

ChatGPT Sites 내부에선 어떻게 돌아갈까?

행복한 수지아빠 — Fri, 24 Jul 2026 15:03:48 +0900

ChatGPT의 Sites 기능은 단순히 HTML 파일을 만들어 다운로드해 주는 기능이 아닙니다. 대화에서 웹사이트를 기획하고 코드를 작성한 뒤, 빌드·버전 저장·호스팅·외부 URL 연결까지 처리하는 관리형 웹 배포 서비스에 가깝습니다.

핵심 구조를 먼저 한 문장으로 정리하면 다음과 같습니다.

ChatGPT의 Work VM은 웹사이트를 만드는 작업실이고, Sites는 완성된 소스와 빌드 산출물을 별도의 관리형 Worker 환경에 배포해 외부에서 접속할 수 있게 하는 서비스입니다.

따라서 작업에 사용한 VM이 종료되거나 정리되더라도, 이미 배포된 사이트는 별도의 운영 환경에서 계속 제공될 수 있습니다.

실제로 생성된 사이트도 로컬 작업 폴더가 정리된 후에도 Sites 서비스에 다음 정보가 남아 있었습니다.

사이트 프로젝트 정보
공개 주소
공개 범위
Git 커밋 기준 소스 버전
전체 소스 아카이브
배포된 운영 버전
사이트 대표 이미지
접근 권한 설정

이 원리를 이해하려면 Work VM, Sites, Vinext, Vite, Cloudflare Worker의 역할을 분리해서 봐야 합니다.

1. ChatGPT Sites는 하나의 프로그램이 아니라 전체 배포 과정이다

Sites를 하나의 웹 프레임워크나 서버 프로그램으로 생각하면 구조가 혼란스러워집니다.

Sites는 대략 다음 기능을 하나로 묶은 서비스입니다.

사이트 프로젝트 생성
작업용 소스 코드 준비
이미지와 정적 파일 관리
React·Next.js 코드 빌드
Worker용 서버 코드 생성
빌드 산출물 검증
소스 버전 저장
운영 환경 배포
chatgpt.site 주소 연결
공개·비공개 접근 권한 관리
환경변수와 API 키 관리
데이터베이스와 파일 저장소 연결

전체 흐름은 다음과 같습니다.

여기에서 Work VM은 최종 운영 서버가 아닙니다. 코드를 만들고 검사하는 임시 개발환경입니다.

운영 사이트는 Sites가 저장하고 배포한 별도의 버전으로 서비스됩니다.

2. Work VM은 웹사이트가 계속 실행되는 서버가 아니다

ChatGPT Work 환경에서 사이트를 만들면 /workspace/sites/... 같은 작업 경로에 소스 코드가 준비됩니다.

이번에 확인한 WMU 사이트도 다음 경로로 복원됐습니다.

/workspace/sites/wmu-global-ai-hub

이 폴더에는 일반적인 웹 프로젝트처럼 다음 파일들이 들어 있었습니다.

wmu-global-ai-hub/
├─ app/
│  ├─ page.tsx
│  ├─ layout.tsx
│  ├─ globals.css
│  └─ chatgpt-auth.ts
├─ public/
│  ├─ hero-women-network.png
│  └─ favicon.svg
├─ worker/
│  └─ index.ts
├─ build/
│  └─ sites-vite-plugin.ts
├─ scripts/
│  ├─ build-verified.sh
│  └─ validate-artifact.sh
├─ .openai/
│  └─ hosting.json
├─ vite.config.ts
└─ package.json

ChatGPT는 이 작업 폴더에서 다음 작업을 수행합니다.

React 컴포넌트 작성
CSS 디자인
이미지 파일 배치
모바일 반응형 적용
버튼과 모달 같은 상호작용 구현
빌드 실행
빌드 산출물 검사
배포할 소스 버전 확정

하지만 외부 사용자가 이 작업 폴더에 직접 접속하는 것은 아닙니다.

Work VM은 개발자 PC와 비슷하고, Sites 운영 환경은 Vercel·Cloudflare Workers 같은 배포 플랫폼과 비슷한 역할을 합니다.

3. VM이 정리됐는데 사이트가 남아 있었던 이유

이번 분석 과정에서 로컬 /workspace를 검색했을 때 처음에는 사이트 소스와 .openai/hosting.json이 발견되지 않았습니다.

이전 작업공간이 자동 정리된 상태였기 때문입니다. 그러나 Sites 서비스에는 WMU Global AI Hub 프로젝트가 남아 있었습니다.

확인된 원격 정보는 다음과 같습니다.

항목확인된 상태

프로젝트	WMU Global AI Hub
공개 주소	wmu-global-ai-hub.tommykim1981.chatgpt.site
공개 범위	Public
저장된 버전	1개
소스 기준	Git 커밋
소스 아카이브	약 3.3MB
커스텀 도메인	없음
운영 환경변수	없음
D1 데이터베이스	없음
R2 파일 저장소	없음

Sites가 저장한 원격 버전을 통해 사이트 체크아웃을 다시 복원할 수 있었습니다.

따라서 Sites에는 최소한 다음 세 가지 계층이 존재한다고 이해할 수 있습니다.

1. 로컬 작업본
   ChatGPT가 현재 수정하는 파일

2. 저장된 소스 버전
   특정 Git 커밋과 소스 아카이브

3. 운영 배포본
   외부 URL에서 서비스되는 실행 버전

이 세 가지는 서로 같아 보이지만 목적이 다릅니다.

로컬 작업본

현재 편집 중인 코드입니다. 아직 외부 사용자에게 공개되지 않은 변경사항이 포함될 수 있습니다.

저장된 소스 버전

특정 시점의 소스를 변경 불가능한 버전으로 저장한 것입니다. 나중에 복원하거나 배포 이력을 확인하는 기준이 됩니다.

운영 배포본

저장된 버전을 실제 운영 환경에서 실행하도록 배포한 결과입니다. 사용자가 브라우저에서 보는 것은 이 운영 배포본입니다.

4. .openai/hosting.json은 어떤 역할을 할까?

Sites 프로젝트에는 .openai/hosting.json이라는 파일이 있습니다.

WMU 사이트에서 확인된 형태는 다음과 같습니다.

{
  "d1": null,
  "project_id": "사이트 프로젝트 식별자",
  "r2": null
}

이 파일에 웹사이트 전체 설정이 들어 있는 것은 아닙니다. Sites 서비스와 로컬 소스 코드를 연결하는 프로젝트 표식에 가깝습니다.

각 필드의 의미는 다음과 같습니다.

필드역할

project_id	현재 코드가 어느 Sites 프로젝트에 속하는지 식별
d1	Sites가 연결한 D1 데이터베이스 바인딩
r2	Sites가 연결한 R2 파일 저장소 바인딩

현재 WMU 사이트는 랜딩 페이지이기 때문에 D1과 R2가 모두 null입니다.

데이터베이스나 업로드 기능을 추가하면 Sites가 해당 리소스를 만들고 논리적 바인딩을 이 파일과 연결할 수 있습니다.

중요한 점은 API 키나 비밀번호를 hosting.json에 넣지 않는다는 것입니다. 비밀정보는 Sites의 운영 환경변수 기능으로 관리해야 합니다.

5. 실제 사이트는 어떤 기술로 만들어졌을까?

NextJs로 만든 사이트의 package.json을 확인한 결과 주요 구성은 다음과 같았습니다.

기술역할

React 19	UI 컴포넌트 작성
Next.js 16	페이지와 서버 기능 구성
Vite 8	개발 서버와 프로덕션 빌드
Vinext	Next.js 기능을 Vite·Worker 환경에 연결
Cloudflare Vite Plugin	Worker 환경 빌드와 로컬 실행
Wrangler	Cloudflare Worker 개발 도구
TypeScript	타입이 있는 JavaScript 개발
Tailwind CSS	CSS 도구
Drizzle ORM	D1 같은 SQL 데이터베이스 연결 준비

이 중에서 가장 낯선 기술은 Vinext입니다.

6. Vinext는 플랫폼이 아니라 호환 계층이다

Vinext는 호스팅 서비스나 클라우드 플랫폼 이름이 아닙니다.

Next.js 애플리케이션의 API와 실행 방식을 Vite 위에서 다시 구현해, Cloudflare Workers 같은 환경에서 실행할 수 있게 만드는 도구입니다.

Cloudflare의 공식 Vinext 저장소는 Vinext를 Next.js API 표면을 Vite 위에서 재구현하는 플러그인으로 설명합니다. App Router, Pages Router, React Server Components, Server Actions, Middleware, Route Handler, ISR과 정적 내보내기 등을 지원하며, Cloudflare Workers와 가장 깊게 통합됩니다. Cloudflare Vinext 공식 저장소

전체 관계는 다음과 같습니다.

Next.js 코드를 그대로 Cloudflare Worker에 넣는다고 자동으로 실행되지는 않습니다.

Next.js는 다음과 같은 자체 실행 규칙을 가지고 있기 때문입니다.

파일 기반 라우팅
App Router
서버 컴포넌트
클라이언트 컴포넌트
Route Handler
서버 렌더링
데이터 캐시
이미지 최적화
서버 액션

Vinext는 이런 Next.js의 기능을 Vite 빌드와 Worker의 요청 처리 방식에 맞춰 연결합니다.

WMU 사이트의 vite.config.ts에는 실제로 다음 플러그인이 등록되어 있었습니다.

import vinext from "vinext";
import { defineConfig } from "vite";
import { sites } from "./build/sites-vite-plugin";

export default defineConfig({
  plugins: [
    vinext(),
    sites(),
  ],
});

여기서 각 플러그인의 역할은 다음과 같습니다.

vinext()
→ Next.js 호환 기능과 라우팅을 Vite 빌드에 연결

sites()
→ 빌드 산출물에 Sites 배포 메타데이터를 포함

cloudflare()
→ Worker 런타임과 바인딩을 Vite에 연결

7. 왜 Next.js인데 next build가 아니라 Vinext를 사용할까?

일반적인 Next.js 프로젝트는 다음 명령으로 빌드합니다.

next build

하지만 이 Sites 프로젝트는 다음과 같은 방식으로 빌드됩니다.

vinext build

Vinext 공식 설명에 따르면, Vinext는 next build 결과물을 가져와 변환하는 방식이 아니라 Next.js API를 Vite 위에서 다시 구현하는 방식입니다. Cloudflare Vinext 공식 저장소

즉, 개념적으로 다음과 같은 차이가 있습니다.

일반적인 Next.js 배포

Next.js 코드
→ next build
→ Node.js 또는 Vercel용 결과물

Sites에서 확인된 구조

Next.js 코드
→ Vinext
→ Vite
→ Cloudflare Worker 호환 결과물

이 방식의 장점은 개발자가 React와 Next.js 스타일로 사이트를 작성하면서도 최종 실행 환경을 Worker 구조로 만들 수 있다는 점입니다.

8. 빌드하면 어떤 산출물이 만들어질까?

WMU 사이트의 빌드 검증 스크립트는 최소한 다음 두 파일이 있어야 배포 가능한 산출물로 인정합니다.

dist/server/index.js
dist/.openai/hosting.json

각 파일의 역할은 다음과 같습니다.

dist/server/index.js

Worker에서 실행할 서버 코드입니다.

최종 모듈은 기본 내보내기 객체를 제공하고, 그 안에 호출 가능한 fetch() 함수가 있어야 합니다.

개념적인 형태는 다음과 같습니다.

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello");
  }
};

dist/.openai/hosting.json

현재 빌드가 어느 Sites 프로젝트와 연결되는지 알려 주는 배포 메타데이터입니다.

정적 자산

이 외에도 다음 파일들이 빌드 산출물에 포함될 수 있습니다.

dist/
├─ server/
│  └─ index.js
├─ assets/
│  ├─ JavaScript 번들
│  ├─ CSS
│  ├─ 폰트
│  └─ 이미지
└─ .openai/
   ├─ hosting.json
   └─ drizzle/

Drizzle 데이터베이스 마이그레이션이 있다면 dist/.openai/drizzle/도 함께 포함됩니다.

9. Worker 서버 코드는 왜 필요할까?

사이트가 단순한 랜딩 페이지라면 HTML, CSS, JavaScript와 이미지만 있어도 충분해 보입니다. 그런데 Sites 프로젝트에는 왜 Worker 서버 코드가 포함될까요?

이유는 배포 형식을 정적 사이트로 제한하지 않고, 서버 렌더링과 백엔드 기능까지 처리할 수 있도록 만들기 위해서입니다.

Worker 서버 코드는 다음 기능을 담당할 수 있습니다.

들어온 HTTP 요청 처리
URL별 페이지 라우팅
서버 컴포넌트 실행
서버 렌더링
API Route 실행
로그인 사용자 확인
환경변수 접근
데이터베이스 조회
파일 저장소 접근
외부 API 호출
이미지 최적화
오류 처리

Cloudflare Workers에서는 외부 HTTP 요청이 fetch() 핸들러로 전달됩니다. 이 함수는 Request, 환경 바인딩인 env, 실행 컨텍스트인 ctx를 받아 Response를 반환합니다. Cloudflare Workers Fetch Handler 공식 문서

export default {
  async fetch(request, env, ctx) {
    return new Response("응답");
  },
};

WMU 사이트에서도 같은 형태를 확인할 수 있었습니다.

const worker = {
  async fetch(request, env, ctx) {
    return handler.fetch(request, env, ctx);
  },
};

export default worker;

여기서 handler는 Vinext가 제공하는 Next.js App Router 실행기입니다.

즉, Worker가 직접 모든 페이지를 구성하는 것이 아니라 Vinext의 핸들러에게 요청을 전달합니다.

10. 정적 파일과 Worker는 어떻게 함께 동작할까?

Sites의 배포물은 정적 자산과 서버 코드를 함께 포함할 수 있습니다.

배포 버전
├─ 정적 자산
│  ├─ 이미지
│  ├─ CSS
│  ├─ 브라우저 JavaScript
│  └─ 폰트
└─ Worker 서버
   ├─ 페이지 라우팅
   ├─ 서버 렌더링
   ├─ API
   └─ 외부 서비스 연동

Cloudflare Workers는 HTML, CSS, 이미지 같은 정적 자산을 Worker와 함께 배포할 수 있습니다. Cloudflare는 이런 정적 파일을 캐시하고 브라우저에 제공할 수 있다고 설명합니다. Cloudflare Workers Static Assets 공식 문서

Worker 코드에서는 env.ASSETS 바인딩을 통해 정적 파일을 직접 가져올 수도 있습니다.

return env.ASSETS.fetch(request);

Cloudflare 공식 문서에서도 Assets 바인딩을 사용해 env.ASSETS.fetch() 형태로 정적 자산을 가져올 수 있다고 설명합니다. Cloudflare Assets Binding 공식 문서

WMU 사이트에서는 이미지 최적화 경로가 들어오면 다음과 같은 처리를 합니다.

if (url.pathname === "/_vinext/image") {
  return handleImageOptimization(request, {
    fetchAsset: (path) =>
      env.ASSETS.fetch(
        new Request(new URL(path, request.url))
      ),
  });
}

일반적인 요청 흐름은 다음과 같습니다.

사이트가 대부분 정적이더라도 하나의 Worker 배포 안에서 정적 자산과 동적 요청을 통합해 처리할 수 있습니다.

11. 모든 페이지 요청이 Worker를 거쳐야 할까?

실제 라우팅 우선순위와 캐시 정책은 Sites의 비공개 배포 설정에 따라 달라질 수 있습니다.

개념적으로는 다음 두 방식이 가능합니다.

정적 자산 우선 처리

이미 생성된 CSS, JavaScript, 이미지 요청은 정적 자산 계층에서 바로 반환하고, 동적 요청만 Worker로 전달합니다.

정적 파일 요청 → CDN·Assets
동적 페이지 요청 → Worker
API 요청 → Worker

Worker가 요청을 분류

모든 요청이 Worker 진입점으로 전달되고, Worker가 정적 자산과 페이지 요청을 구분합니다.

모든 요청 → Worker → Assets 또는 서버 핸들러

WMU 프로젝트 소스에서는 Worker가 이미지 최적화 요청을 직접 분기하고, 나머지 요청은 Vinext 핸들러로 전달하는 것을 확인했습니다.

12. Sites는 백엔드도 만들 수 있을까?

가능합니다. Worker 서버 코드가 포함되는 가장 중요한 이유 중 하나입니다.

Sites에서 구현할 수 있는 백엔드 기능은 다음과 같습니다.

기능구현 방식

REST API	Next.js Route Handler
폼 접수	POST /api/contact
외부 AI 호출	Worker에서 fetch()
회원별 페이지	로그인 헤더 확인 후 렌더링
게시물 저장	D1 데이터베이스
이미지 업로드	R2 저장소
결제 Webhook	공개 API 경로에서 수신
Telegram Webhook	Telegram이 Sites API로 POST
이메일 발송	외부 이메일 API 호출
관리자 기능	인증 + D1
다국어 콘텐츠	URL·헤더·데이터에 따라 렌더링

예를 들어 문의 폼 API는 다음처럼 만들 수 있습니다.

export async function POST(request: Request) {
  const form = await request.json();

  if (!form.email || !form.message) {
    return Response.json(
      { error: "필수 항목이 없습니다." },
      { status: 400 },
    );
  }

  return Response.json({
    ok: true,
  });
}

브라우저에서는 다음 주소로 요청할 수 있습니다.

POST /api/contact

Sites가 배포된 후에는 다음과 같은 외부 주소가 됩니다.

POST https://사이트주소.chatgpt.site/api/contact

13. Worker에서 외부 API도 호출할 수 있을까?

Worker는 표준 fetch()를 이용해 외부 HTTP API를 호출할 수 있습니다. Cloudflare 공식 문서도 Workers 내부에서 Fetch API를 이용해 HTTP 리소스를 비동기로 가져올 수 있다고 설명합니다. Cloudflare Workers Fetch API 공식 문서

예를 들어 DeepSeek API를 호출하는 백엔드는 다음과 같은 구조로 만들 수 있습니다.

export async function POST(request: Request) {
  const { message } = await request.json();

  const response = await fetch(
    "https://api.deepseek.com/chat/completions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.DEEPSEEK_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: "deepseek-v4-flash",
        messages: [
          {
            role: "user",
            content: message,
          },
        ],
      }),
    },
  );

  const result = await response.json();
  return Response.json(result);
}

이 구조를 이용하면 다음 기능을 만들 수 있습니다.

웹사이트 AI 상담
콘텐츠 자동 요약
번역
챗봇
상품 설명 생성
한국어 학습 피드백
퀴즈 자동 생성
관리자용 데이터 분석

다만 API 키를 브라우저 코드에 직접 넣으면 안 됩니다.

잘못된 구조
브라우저 → DeepSeek API
API 키가 사용자에게 노출될 수 있음

권장 구조
브라우저 → Sites Worker → DeepSeek API
API 키는 Worker 환경변수에서만 사용

14. API 키와 운영 환경변수는 어디에 저장할까?

사이트 소스에 API 키를 직접 작성하면 Git 기록과 빌드 산출물에 비밀정보가 남을 수 있습니다.

예를 들어 다음 코드는 피해야 합니다.

const apiKey = "실제 API 키";

Sites에는 운영용 환경변수를 별도로 등록하는 기능이 있습니다.

개념적인 구조는 다음과 같습니다.

환경변수는 일반 값과 비밀값으로 구분할 수 있습니다.

일반 환경변수
PUBLIC_SITE_NAME=WMU Global Hub

비밀 환경변수
DEEPSEEK_API_KEY=...
TELEGRAM_BOT_TOKEN=...

비밀값은 소스 코드나 hosting.json에 넣지 않고 Sites의 운영 설정에 보관해야 합니다.

WMU 사이트는 현재 외부 API를 사용하지 않기 때문에 운영 환경변수가 등록되어 있지 않았습니다.

15. D1 데이터베이스는 어떤 역할을 할까?

D1은 Cloudflare Workers에서 사용하는 서버리스 SQL 데이터베이스입니다. SQLite와 호환되는 방식으로 데이터를 저장하고 조회할 수 있습니다.

Cloudflare 공식 문서에 따르면 Worker는 D1 바인딩을 통해 SQL 쿼리를 실행할 수 있습니다. Cloudflare D1 Worker API 공식 문서

Sites에서 D1을 연결하면 다음 기능을 만들 수 있습니다.

회원 프로필
문의 내역
게시판
학습 진도
퀴즈 문제와 답안
포인트 내역
예약 데이터
상품 정보
주문 상태
AI 대화 기록

Worker에서는 보통 다음과 같은 방식으로 접근합니다.

export default {
  async fetch(request, env) {
    const result = await env.DB
      .prepare("SELECT * FROM users WHERE id = ?")
      .bind("user-123")
      .first();

    return Response.json(result);
  },
};

Cloudflare는 바인딩을 통해 Worker가 D1 같은 플랫폼 리소스에 접근한다고 설명합니다. Cloudflare Workers Bindings 공식 문서

WMU 사이트의 설정에는 D1이 연결되어 있지 않았습니다.

{
  "d1": null
}

현재는 실제 회원·게시물·포인트 데이터를 저장하지 않는 소개용 사이트이기 때문입니다.

16. R2 파일 저장소는 어떤 역할을 할까?

R2는 이미지, 동영상, PDF, 첨부파일 같은 객체 파일을 저장하는 용도입니다.

Sites에 R2를 연결하면 다음 기능을 구현할 수 있습니다.

회원 프로필 이미지
강의 자료 업로드
PDF 교재 저장
상품 이미지
라이브커머스 영상
사용자 제출 과제
AI 생성 이미지
관리자 첨부파일

정적 이미지와 사용자 업로드 파일은 구분해야 합니다.

정적 이미지

사이트를 만들 때부터 프로젝트에 포함된 파일입니다.

public/hero-women-network.png

사이트를 다시 배포해야 이미지가 변경됩니다.

사용자 업로드 파일

사이트 운영 중 사용자가 올리는 파일입니다.

사용자 → Worker 업로드 API → R2 저장

사이트를 다시 빌드하지 않아도 파일을 추가하고 삭제할 수 있습니다.

WMU 사이트는 현재 R2를 사용하지 않습니다.

{
  "r2": null
}

17. ChatGPT 로그인도 사용할 수 있을까?

WMU 프로젝트에는 chatgpt-auth.ts라는 인증 보조 코드가 포함되어 있었습니다.

이 코드는 Sites 실행환경이 전달하는 인증 헤더를 읽어 사용자 이메일과 이름을 확인하는 구조입니다.

확인된 주요 헤더는 다음과 같았습니다.

oai-authenticated-user-email
oai-authenticated-user-full-name
oai-authenticated-user-full-name-encoding

개념적인 동작은 다음과 같습니다.

사이트 코드에서는 다음처럼 사용자를 확인할 수 있습니다.

const email = requestHeaders.get(
  "oai-authenticated-user-email"
);

인증되지 않은 사용자는 로그인 경로로 이동시킬 수 있습니다.

/signin-with-chatgpt

현재 WMU 사이트의 접근 모드는 Public이기 때문에 누구나 사이트를 열 수 있습니다. 다만 사이트 일부 기능만 로그인 사용자에게 제공하는 식으로 확장할 수 있습니다.

18. 공개 사이트와 비공개 사이트는 무엇이 다를까?

Sites는 프로젝트별로 접근 정책을 관리합니다.

현재 WMU 사이트는 공개 모드입니다.

access_mode: public

공개 사이트는 외부 사용자가 chatgpt.site 주소로 접속할 수 있습니다.

비공개 또는 제한된 사이트라면 특정 사용자나 그룹만 접근하도록 구성할 수 있습니다.

공개 사이트
→ 누구나 URL로 접속

제한된 사이트
→ 인증된 사용자만 접속

사용자 지정 접근
→ 허용된 사용자·그룹만 접속

접근 정책은 애플리케이션 코드와 별도로 Sites 배포 계층에서 관리됩니다.

이 차이는 중요합니다.

애플리케이션 코드에 로그인 페이지가 있어도 Sites 접근 정책이 Public이면 기본 사이트 주소 자체는 공개될 수 있습니다. 반대로 애플리케이션이 공개 페이지처럼 보여도 Sites 접근 정책이 제한적이면 허용된 사용자만 진입할 수 있습니다.

19. chatgpt.site 주소는 어떻게 연결될까?

Sites에서 프로젝트를 만들면 프로젝트별 슬러그를 기반으로 운영 URL이 만들어집니다.

WMU 사이트는 다음 주소를 사용합니다.

https://wmu-global-ai-hub.tommykim1981.chatgpt.site

주소 구성은 대략 다음처럼 이해할 수 있습니다.

프로젝트 슬러그
        +
사용자 또는 소유자 식별 영역
        +
chatgpt.site

Sites는 이 주소를 배포된 운영 버전과 연결합니다.

개발자가 직접 Nginx를 설정하거나 SSL 인증서를 설치할 필요가 없습니다.

[Inference] DNS, TLS 인증서, 라우팅과 배포 대상 연결은 Sites의 관리형 인프라에서 처리되는 것으로 보입니다.

20. 커스텀 도메인도 연결할 수 있을까?

Sites 서비스에는 프로젝트별 커스텀 도메인을 조회하고 관리하는 구조가 있습니다.

WMU 사이트에는 현재 커스텀 도메인이 연결되어 있지 않습니다.

Custom domains: 없음

따라서 현재는 기본 chatgpt.site 주소만 사용합니다.

커스텀 도메인이 지원되는 프로젝트라면 개념적으로 다음과 같이 연결할 수 있습니다.

기본 주소
wmu-global-ai-hub....chatgpt.site

사용자 도메인
www.example.com

두 주소가 동일한 Sites 프로젝트의 운영 배포본으로 연결되는 방식입니다.

구체적인 DNS 설정과 지원 범위는 Sites의 현재 도메인 연결 정책을 확인해야 합니다.

21. Sites 배포는 어떤 단계를 거칠까?

Sites 배포는 단순히 폴더를 서버에 복사하는 작업이 아닙니다.

확인된 프로젝트 구조를 기준으로 보면 다음 단계로 나뉩니다.

1단계: 소스 준비

React·Next.js 코드와 이미지, CSS, Worker 진입점, 배포 메타데이터를 준비합니다.

2단계: 로컬 빌드

Vinext가 Next.js 호환 기능을 해석하고 Vite가 Worker용 산출물을 만듭니다.

vinext build

3단계: 산출물 검증

프로젝트의 검증 스크립트는 다음 조건을 확인합니다.

dist/server/index.js가 존재하는가?
dist/.openai/hosting.json이 존재하는가?
서버 모듈이 ESM 형식인가?
기본 내보내기에 fetch()가 있는가?
hosting.json이 유효한 JSON인가?

검증 코드의 핵심은 다음과 같습니다.

const worker = await import(workerUrl.href);

if (
  !worker.default ||
  typeof worker.default.fetch !== "function"
) {
  throw new Error(
    "Worker 진입점이 올바르지 않습니다."
  );
}

4단계: 소스 커밋 저장

배포할 소스를 특정 Git 커밋으로 확정합니다.

5단계: 불변 버전 생성

해당 커밋과 소스 아카이브를 Sites의 저장된 버전으로 만듭니다.

6단계: 운영 배포

저장된 버전을 관리형 Worker 환경에 배포합니다.

7단계: 배포 상태 확인

배포 상태가 성공인지 실패인지 확인합니다.

pending
→ building
→ publishing
→ succeeded 또는 failed

8단계: 운영 URL 연결

성공한 운영 배포본을 사이트의 현재 공개 URL과 연결합니다.

22. 소스 저장과 배포는 왜 분리되어 있을까?

소스 버전과 운영 배포를 분리하면 같은 소스를 다시 배포하거나 이전 버전으로 돌아갈 수 있습니다.

예를 들어 버전 3에서 문제가 발생하면 이전에 저장된 버전 2를 다시 운영에 배포하는 구조를 만들 수 있습니다.

소스만 저장됐다고 외부에 공개되는 것도 아니고, 로컬 코드가 수정됐다고 운영 사이트가 즉시 바뀌는 것도 아닙니다.

운영 사이트가 바뀌려면 수정된 소스를 새 버전으로 저장하고 그 버전을 배포해야 합니다.

23. Sites와 일반 VPS는 무엇이 다를까?

가장 큰 차이는 서버 프로세스의 유지 방식입니다.

구분ChatGPT Sites일반 VPS

실행 방식	요청 기반 Worker	상시 실행 프로세스
서버 관리	관리형	사용자가 직접 관리
포트 개방	일반적으로 불필요	직접 설정
Nginx 설정	일반적으로 불필요	직접 구성
SSL	관리형 URL에 연결	직접 또는 인증서 자동화
정적 파일	Assets로 배포	디스크·Nginx 사용
API	Worker 요청 처리	Node·Python 서버
데이터베이스	D1 등 바인딩	PostgreSQL·MySQL 직접 운영
파일 저장	R2	로컬 디스크·S3
장기 실행 데몬	부적합	적합
Telegram 폴링	부적합	적합
Telegram Webhook	적합	적합
OpenClaw Gateway	부적합	적합
일반 TCP 서버	부적합	적합

Sites는 웹 요청을 받아 짧게 처리하고 응답하는 서비스에 적합합니다.

반면 VPS는 프로세스를 계속 실행해야 하는 프로그램에 적합합니다.

24. 왜 Work VM에서는 Telegram 봇이 멈췄는데 Sites 웹사이트는 계속 열릴까?

앞서 Work VM에서 Hermes와 OpenClaw를 실행해 Telegram 봇을 연결했지만, 장기 실행 중 다음 오류가 확인됐습니다.

Network access to
https://api.telegram.org:443
was blocked by policy

Hermes나 OpenClaw의 프로그램 문제가 아니라 Work VM의 장기 실행 프로세스와 외부 네트워크 정책 때문이었습니다.

Telegram 폴링 봇은 다음 구조입니다.

이 프로그램은 다음 조건을 만족해야 합니다.

프로세스가 계속 살아 있어야 함
Telegram 서버에 반복 접속해야 함
네트워크 연결이 유지돼야 함
메모리와 세션을 계속 유지해야 함

반면 Sites는 요청 기반입니다.

Worker가 24시간 하나의 프로세스로 실행되는 것이 아니라, 요청이 들어왔을 때 실행될 수 있는 코드로 배포됩니다.

그래서 Work VM이 없어도 운영 사이트가 계속 응답할 수 있습니다.

25. Telegram을 Sites와 연결하는 방법은 없을까?

OpenClaw 전체 Gateway를 Sites에 실행하는 방식은 적합하지 않습니다. 하지만 Telegram Webhook 방식의 경량 챗봇은 만들 수 있습니다.

폴링 방식

봇이 Telegram 서버에 계속 질문합니다.

새 메시지 있습니까?
새 메시지 있습니까?
새 메시지 있습니까?

장기 실행 프로세스가 필요합니다.

Webhook 방식

Telegram이 새 메시지가 생겼을 때 Sites API로 알려 줍니다.

Telegram
→ POST /api/telegram/webhook
→ Sites Worker

전체 구조는 다음과 같습니다.

이 방식은 Worker가 계속 실행될 필요가 없습니다.

Telegram이 메시지를 전달할 때만 Worker가 실행됩니다.

26. Telegram Webhook 백엔드는 어떻게 구성할까?

개념적인 API 경로는 다음과 같습니다.

POST /api/telegram/webhook

처리 순서는 다음과 같습니다.

Telegram이 메시지 업데이트를 전송
요청이 Telegram에서 온 것인지 검증
메시지를 보낸 사용자 ID 확인
허용된 사용자만 처리
메시지 내용 추출
DeepSeek API 호출
답변 내용 정리
Telegram sendMessage API 호출
Telegram에 HTTP 200 응답

간단한 코드 구조는 다음과 같습니다.

export async function POST(request: Request) {
  const update = await request.json();

  const message = update.message;
  if (!message?.text) {
    return Response.json({ ok: true });
  }

  const answer = await askDeepSeek(message.text);

  await sendTelegramMessage(
    message.chat.id,
    answer,
  );

  return Response.json({ ok: true });
}

DeepSeek 호출 함수는 다음과 같이 분리할 수 있습니다.

async function askDeepSeek(message: string) {
  const response = await fetch(
    "https://api.deepseek.com/chat/completions",
    {
      method: "POST",
      headers: {
        Authorization:
          `Bearer ${process.env.DEEPSEEK_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: "deepseek-v4-flash",
        messages: [
          {
            role: "system",
            content:
              "질문에 자연스러운 한국어로 답하세요.",
          },
          {
            role: "user",
            content: message,
          },
        ],
      }),
    },
  );

  const result = await response.json();
  return result.choices[0].message.content;
}

Telegram 발송 함수는 다음과 같습니다.

async function sendTelegramMessage(
  chatId: number,
  text: string,
) {
  await fetch(
    `https://api.telegram.org/bot${
      process.env.TELEGRAM_BOT_TOKEN
    }/sendMessage`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: chatId,
        text,
      }),
    },
  );
}

비밀값은 Sites 운영 환경변수에 저장합니다.

DEEPSEEK_API_KEY
TELEGRAM_BOT_TOKEN
TELEGRAM_WEBHOOK_SECRET
ALLOWED_TELEGRAM_USER_ID

27. Sites에서 OpenClaw 전체를 실행하기 어려운 이유

OpenClaw는 단순한 API 함수가 아닙니다.

OpenClaw Gateway는 다음과 같은 상태를 계속 유지합니다.

Telegram·Discord 등 채널 연결
세션
대화 기록
작업 큐
도구 실행
파일 접근
장기 실행 작업
백그라운드 이벤트
주기적 작업
Gateway WebSocket

이런 프로그램은 일반적으로 다음 환경이 적합합니다.

AWS Lightsail
일반 VPS
EC2
Docker 서버
Railway의 장기 실행 서비스
Fly.io VM
집 PC
Mac mini
NAS

Sites의 Worker는 HTTP 요청을 받아 처리하는 백엔드에는 적합하지만, OpenClaw 전체 Gateway를 계속 실행하는 서버를 대체하는 용도는 아닙니다.

다만 OpenClaw의 일부 기능을 API 형태로 분리하면 Sites와 조합할 수 있습니다.

Sites
→ 사용자 화면과 Webhook

외부 VPS
→ OpenClaw Gateway

Sites와 VPS
→ HTTPS API로 연결

28. Worker 백엔드의 상태는 어디에 저장할까?

Worker 코드의 전역 변수나 메모리에 중요한 상태를 계속 보관하면 안 됩니다.

예를 들어 다음 구조는 신뢰하기 어렵습니다.

let userPoints = 0;

요청마다 실행 인스턴스가 달라지거나 재시작될 수 있기 때문입니다.

상태는 용도에 맞는 저장소에 넣어야 합니다.

데이터 유형적합한 저장소

회원·게시물·포인트	D1
이미지·PDF·동영상	R2
간단한 설정·캐시	KV
실시간 상태·동시성	Durable Objects
비밀 API 키	운영 환경변수
정적 사이트 이미지	프로젝트의 public/

WMU 사이트는 현재 실제 운영 데이터를 저장하지 않으므로 별도 저장소를 사용하지 않습니다.

29. 서버 렌더링은 무엇이며 왜 필요할까?

서버 렌더링은 브라우저에서 모든 화면을 만든 뒤 보여 주는 대신, 서버가 먼저 HTML을 만들어 반환하는 방식입니다.

서버 렌더링은 다음 상황에 유용합니다.

로그인 사용자별 화면
데이터베이스를 조회한 페이지
검색엔진이 읽어야 하는 콘텐츠
첫 화면을 빠르게 제공해야 하는 경우
API 키를 브라우저에 노출하지 않아야 하는 경우
서버에서 권한을 검사해야 하는 경우

Vinext는 Next.js의 App Router와 React Server Components를 Worker 환경에서 실행할 수 있도록 연결합니다. Cloudflare Vinext 공식 저장소

30. 정적 사이트라면 Worker를 빼도 되지 않을까?

기술적으로 완전한 정적 사이트라면 HTML, CSS, JavaScript, 이미지만 배포하는 구조도 가능합니다.

하지만 Sites의 표준 프로젝트는 다음 이유로 Worker 형식을 기본으로 사용하는 것으로 보입니다.

정적 사이트와 동적 사이트를 같은 배포 규격으로 관리할 수 있음
나중에 API를 추가하기 쉬움
서버 렌더링 지원
ChatGPT 인증 연결
이미지 최적화
D1·R2 바인딩
Next.js Route Handler 지원
공개·비공개 접근 정책 적용
동적 오류 페이지와 라우팅
외부 API 호출

즉, 지금은 정적인 랜딩 페이지라도 나중에 회원, 게시판, AI 챗봇, 문의 저장 기능을 붙일 수 있는 기반을 갖고 있습니다.

31. 현재 WMU 사이트는 정적 사이트인가, 동적 사이트인가?

정확히는 정적 콘텐츠 중심의 Worker 애플리케이션입니다.

콘텐츠 자체는 대부분 코드에 고정되어 있습니다.

const pillars = [
  {
    title: "배움이 가능성이 되는 곳",
    body: "AI 리터러시부터...",
  },
];

데이터베이스나 외부 API는 사용하지 않습니다.

하지만 다음 동적 기능은 브라우저 React 상태로 작동합니다.

모바일 메뉴 열기
핵심 서비스 탭 전환
스토리 모달 열기와 닫기
스크롤 이동
반응형 레이아웃

배포 형식은 Worker이기 때문에 앞으로 서버 기능을 추가할 수 있습니다.

따라서 다음처럼 구분하는 것이 정확합니다.

콘텐츠 성격
→ 대부분 정적

브라우저 UI
→ 일부 동적

배포 방식
→ Worker 애플리케이션

현재 백엔드 데이터
→ 없음

백엔드 확장 가능성
→ 있음

32. 이미지 파일은 어디에 있고 어떻게 제공될까?

WMU 사이트의 메인 이미지는 다음 파일입니다.

public/hero-women-network.png

CSS에서는 다음처럼 참조합니다.

.hero-art {
  background-image:
    url("/hero-women-network.png");
}

빌드할 때 이 파일은 정적 Assets에 포함됩니다.

외부 사용자가 이미지를 요청하면 Sites의 배포 환경에서 해당 정적 자산을 반환합니다.

Next.js 이미지 최적화 경로를 사용하는 경우 Worker는 원본 이미지를 Assets에서 읽고 이미지 처리 기능을 거쳐 반환할 수도 있습니다.

현재 Worker 코드에는 다음 환경 바인딩이 정의돼 있습니다.

interface Env {
  ASSETS: Fetcher;
  DB: D1Database;
  IMAGES: {
    input(stream: ReadableStream): unknown;
  };
}

여기서 역할은 다음과 같습니다.

바인딩역할

ASSETS	정적 이미지·CSS·JS 파일 접근
DB	D1 데이터베이스 접근
IMAGES	이미지 크기·포맷 최적화

현재 사이트에서 DB를 실제로 사용하는 것은 아니지만 표준 Worker 템플릿에는 연결 형태가 준비되어 있습니다.

33. Sites는 Cloudflare Pages와 같은 것일까?

완전히 같다고 단정할 수는 없습니다.

확인된 프로젝트는 다음 Cloudflare 기술을 사용합니다.

Cloudflare Vite Plugin
Wrangler
Worker fetch() 진입점
Static Assets 바인딩
이미지 처리 바인딩
선택적 D1
선택적 R2
nodejs_compat 호환 플래그

따라서 Cloudflare Workers 호환 배포 구조인 것은 확인할 수 있습니다.

그러나 사용자의 개인 Cloudflare 계정에 직접 Worker가 생성됐다고 확인되지는 않았습니다. Sites가 자체적으로 관리하는 Cloudflare 기반 인프라에 배포하는 구조로 보는 것이 적절합니다.

사용자는 일반적으로 다음 작업을 직접 하지 않습니다.

Cloudflare 계정 연결
Wrangler 로그인
Worker 이름 생성
DNS 레코드 설정
TLS 인증서 설정
Assets 버킷 설정
D1 리소스 ID 직접 관리

이 부분을 Sites 서비스가 대신 관리합니다.

34. 배포한 사이트는 Work VM이 꺼져도 계속 동작할까?

확인된 WMU 사례에서는 로컬 작업공간이 없어졌는데도 Sites의 운영 URL과 원격 버전이 유지됐습니다.

따라서 이미 성공적으로 배포된 사이트의 운영은 Work VM 프로세스에 의존하지 않습니다.

다만 다음은 구분해야 합니다.

계속 동작하는 것

이미 배포된 사이트
정적 이미지와 CSS
Worker 페이지 응답
배포된 API 경로
연결된 D1·R2
운영 환경변수
공개 URL

Work VM이 다시 필요한 것

소스 수정
새 이미지 생성
기능 추가
디자인 변경
새 버전 빌드
새 배포 생성
로컬 미리보기

사이트 수정이 필요하면 원격 저장 버전에서 소스를 다시 복원한 뒤 변경하고 새 버전을 배포할 수 있습니다.

35. Sites로 만들기 적합한 서비스

Sites는 다음과 같은 프로젝트에 잘 맞습니다.

콘텐츠와 소개 사이트

회사 홈페이지
브랜드 사이트
행사 안내
포트폴리오
투자 소개
제품 랜딩 페이지

데이터 기반 웹앱

대시보드
관리자 화면
교육 플랫폼
퀴즈 서비스
게시판
신청·접수 시스템
포인트 관리

AI 기능이 포함된 사이트

AI 상담
번역
문서 요약
콘텐츠 생성
문제 생성
학습 피드백
이미지 분석 결과 표시

Webhook 기반 연동

Telegram 챗봇
결제 결과 수신
GitHub 이벤트
외부 서비스 알림
폼 접수 후 이메일 전송

36. Sites에 적합하지 않은 서비스

다음 기능은 일반 VPS나 전용 백엔드가 더 적합합니다.

OpenClaw Gateway 전체 실행
Telegram 무한 폴링
임의 포트의 TCP 서버
SSH 서버
장기간 실행되는 Python 프로세스
시스템 패키지를 계속 사용하는 데몬
서버 로컬 디스크에 의존하는 프로그램
장기 GPU 작업
지속적인 WebSocket 서버 상태
Docker Compose 전체 스택

Cloudflare Workers 플랫폼 자체에는 Queues, Workflows, Durable Objects, Cron 같은 다양한 기능이 있지만, ChatGPT Sites가 그 기능을 모두 직접 노출한다고 확인된 것은 아닙니다. Sites에서 제공되는 실제 기능 범위 안에서 설계해야 합니다.

37. Sites를 이해하기 위한 가장 쉬운 비유

Sites를 식당으로 비유하면 다음과 같습니다.

Work VM은 주방 테스트 공간

메뉴를 개발함
재료를 준비함
맛을 확인함
접시 구성을 수정함

저장된 사이트 버전은 확정된 레시피

특정 시점의 레시피를 보관함
이전 레시피로 돌아갈 수 있음
누가 무엇을 배포했는지 기준이 됨

Worker는 주문 처리 직원

주문이 들어올 때 실행됨
요청을 해석함
정적 파일이나 서버 결과를 반환함
필요한 경우 데이터베이스와 외부 API를 호출함

Assets는 미리 준비된 음식과 재료

CSS
JavaScript
이미지
폰트
정적 HTML

D1은 주문·회원 장부

회원
게시물
포인트
신청 내역

R2는 창고

이미지
PDF
영상
업로드 파일

chatgpt.site는 식당 주소

외부 사용자가 찾아오는 공개 주소
현재 운영 버전과 연결됨

38. 전체 구조를 한 장으로 정리하면

39. 자주 묻는 질문

ChatGPT가 만든 사이트는 VM 안에서 계속 실행되나요?

아닙니다. VM은 사이트를 만들고 빌드하는 작업환경입니다. 성공적으로 배포된 운영 사이트는 별도의 Sites 운영 환경에서 제공됩니다.

VM 폴더가 삭제되면 사이트도 없어지나요?

이번 WMU 사례에서는 로컬 폴더가 없어져도 원격 소스 버전과 운영 URL이 유지됐습니다. 원격 버전에서 체크아웃을 다시 복원할 수 있었습니다.

Sites는 정적 사이트만 만들 수 있나요?

아닙니다. 정적 자산과 Worker 서버 코드가 함께 배포될 수 있어 API, 서버 렌더링, 인증, 데이터베이스와 외부 API 호출을 구현할 수 있습니다.

Worker는 일반 Node.js 서버인가요?

아닙니다. 계속 실행되는 Node.js 프로세스가 아니라 HTTP 요청을 fetch() 핸들러로 처리하는 서버리스 런타임입니다.

백엔드 API를 만들 수 있나요?

가능합니다. Next.js Route Handler 또는 Worker 코드를 이용해 REST API와 Webhook을 만들 수 있습니다.

데이터베이스도 가능한가요?

Sites에서 D1 바인딩을 연결할 수 있는 구조가 확인됐습니다. 현재 WMU 사이트는 데이터베이스를 사용하지 않습니다.

이미지 업로드도 가능한가요?

R2 저장소를 연결하면 구현할 수 있는 구조입니다. 현재 WMU 사이트는 프로젝트에 포함된 정적 이미지만 사용합니다.

DeepSeek API를 연결할 수 있나요?

Worker의 fetch()로 외부 API를 호출하고, API 키를 Sites의 비밀 환경변수에 저장하는 구조로 구현할 수 있습니다.

Telegram 봇도 만들 수 있나요?

Webhook 방식의 Telegram 봇은 적합합니다. 반면 계속 실행되는 폴링 방식이나 OpenClaw 전체 Gateway는 Sites보다 VPS가 적합합니다.

Sites에 OpenClaw를 설치할 수 있나요?

OpenClaw의 전체 Gateway는 장기 실행 프로세스와 지속적인 채널 연결이 필요하므로 Worker 실행 모델과 맞지 않습니다. 일부 기능을 API 또는 Webhook으로 분리하는 방식은 가능합니다.

사용자의 Cloudflare 대시보드에서 Worker를 볼 수 있나요?

확인할 수 없습니다. 현재 프로젝트는 Cloudflare Worker 호환 기술을 사용하지만, 사용자의 개인 Cloudflare 계정에 직접 배포됐다는 정보는 확인되지 않았습니다. Sites가 관리하는 인프라에 배포되는 구조로 이해하는 것이 적절합니다.

40. 결론: Sites는 ‘코드 생성기’보다 ‘관리형 웹 배포 시스템’에 가깝다

ChatGPT Sites의 핵심은 예쁜 웹페이지 코드를 생성하는 데서 끝나지 않습니다.

사이트가 외부에서 실제로 작동하려면 다음 과정이 모두 필요합니다.

기획
→ 디자인
→ React·Next.js 구현
→ Vinext·Vite 빌드
→ Worker 산출물 생성
→ 정적 Assets 패키징
→ 산출물 검증
→ 소스 버전 저장
→ 운영 배포
→ 공개 URL 연결
→ 접근 정책 적용

Sites는 이 과정을 하나의 작업 흐름으로 묶습니다.

Work VM은 사이트를 만드는 공간이고, Vinext는 Next.js를 Vite·Worker 환경에 연결하며, Worker는 외부 요청을 처리합니다. 정적 파일은 Assets로 제공되고, 필요한 경우 D1·R2·환경변수·인증·외부 API를 연결할 수 있습니다.

따라서 Sites는 단순한 정적 홈페이지 제작 도구라기보다 다음에 더 가깝습니다.

React와 Next.js로 만든 프런트엔드와 Worker 백엔드를 빌드하고, 버전으로 저장하고, 관리형 주소와 권한을 붙여 외부에 배포하는 ChatGPT 내장형 풀스택 호스팅 시스템

다만 모든 서버 프로그램을 Sites에서 실행할 수 있는 것은 아닙니다. 웹 요청에 따라 실행되는 API와 Webhook에는 적합하지만, OpenClaw Gateway처럼 계속 살아 있어야 하는 프로그램은 VPS나 장기 실행 컨테이너가 필요합니다.

웹사이트, AI 상담, 교육 플랫폼, 신청 시스템, 관리자 페이지, Telegram Webhook처럼 요청 중심으로 동작하는 서비스라면 Sites의 구조를 활용할 수 있습니다. 반대로 지속적인 프로세스와 자유로운 서버 제어가 핵심이라면 일반 클라우드 서버를 선택해야 합니다.

AI가 ‘도구’가 아니라 ‘팀원’이 되는 회사 (Buzz)

행복한 수지아빠 — Wed, 22 Jul 2026 09:41:30 +0900

잭 도시의 Block이 공개한 협업 플랫폼 ‘Buzz’가 보여주는 미래

우리는 이미 업무에서 인공지능을 사용하고 있다.

메일을 정리하고, 문서를 요약하고, 코드를 작성하고, 회의 내용을 정리한다. 그러나 현재의 AI는 대부분 업무를 돕는 보조 도구에 머물러 있다.

사람이 AI에게 질문한다.
AI가 답변을 만든다.
그리고 실제 업무는 다시 사람이 처리한다.

하지만 AI가 단순히 질문에 답하는 도구가 아니라, 프로젝트에 직접 참여하는 팀원이라면 어떨까?

AI가 팀 채팅방에 들어오고, 과거 대화를 검색하고, 코드를 수정하고, 테스트를 실행하고, 리뷰를 요청한다. 사람은 AI가 수행한 작업을 확인하고 승인한다.

2026년 7월, 잭 도시가 이끄는 Block이 공개한 오픈소스 협업 플랫폼 Buzz는 바로 이런 업무 환경을 지향한다.

Buzz를 한 문장으로 표현하면 다음과 같다.

Slack의 팀 대화, GitHub의 코드 관리, CI/CD 자동화, 사내 검색, AI 에이전트를 하나로 통합한 업무 플랫폼

단순히 여러 서비스를 한 화면에 모은 제품은 아니다.

Buzz가 던지는 더 중요한 질문은 이것이다.

AI는 앞으로 회사에서 어떤 지위로 일하게 될 것인가?

흩어진 업무 도구를 하나로 연결하다

현재 대부분의 개발 조직은 여러 개의 서비스를 동시에 사용한다.

Slack이나 Microsoft Teams에서 대화하고, GitHub에서 코드를 관리한다. GitHub Actions나 Jenkins로 테스트와 배포를 자동화하고, Notion이나 Confluence에 문서를 정리한다.

AI 코딩 도구도 별도로 사용한다.

하나의 프로젝트를 진행하지만 업무 기록은 여러 공간에 흩어진다.

팀원이 Slack에서 기능 개발 방향을 논의한다. 개발자는 GitHub에 코드를 올린다. 테스트 결과는 다른 자동화 도구에 저장된다. 왜 이런 결정을 내렸는지는 문서나 과거 메시지를 다시 찾아야 한다.

시간이 지나면 코드 자체는 남지만, 그 코드가 만들어진 배경은 쉽게 사라진다.

Buzz는 이 모든 활동을 하나의 업무 공간에서 연결하려 한다.

팀 대화
프로젝트 채널
코드 저장소
코드 변경과 리뷰
자동화 워크플로
AI 에이전트의 작업
검색과 감사 기록

사람과 AI가 같은 공간에서 대화하고, 작업하고, 결과를 남기는 구조다.

AI 에이전트를 정식 팀원처럼 다룬다

Buzz에서 가장 눈에 띄는 개념은 AI 에이전트의 위치다.

일반적인 협업 서비스에서 AI는 대개 채팅방에 연결된 봇이다. 질문을 받으면 답변하거나, 특정 명령을 실행하는 정도다.

Buzz는 AI 에이전트를 조금 다르게 다룬다.

사람과 마찬가지로 AI 에이전트도 고유한 신원과 암호화 키를 가질 수 있다. 참여할 수 있는 채널과 접근할 수 있는 프로젝트가 정해지고, 어떤 작업을 수행했는지 활동 기록이 남는다.

예를 들어 버그 수정 에이전트는 다음과 같은 과정을 처리할 수 있다.

팀 채널에 등록된 오류 내용을 확인한다.
관련 프로젝트의 과거 대화를 검색한다.
코드 저장소를 분석한다.
수정 코드를 작성한다.
테스트를 실행한다.
수정안을 제출한다.
사람 개발자에게 리뷰를 요청한다.

중요한 점은 AI가 모든 회사 정보에 자유롭게 접근하는 것이 아니라는 것이다.

AI 에이전트도 사람과 마찬가지로 허용된 채널과 저장소에만 접근하도록 구성할 수 있다. 특정 프로젝트에 참여시키고 싶다면 해당 에이전트를 프로젝트 채널에 초대하는 방식이다.

이는 AI를 단순한 기능이 아니라 권한과 책임 범위를 가진 업무 주체로 취급하는 접근이다.

Git 브랜치 하나가 프로젝트 채팅방이 된다

Buzz가 제시하는 흥미로운 방식 가운데 하나는 Git 브랜치와 채팅 채널을 연결하는 것이다.

개발자가 새로운 기능을 만들기 위해 브랜치를 생성하면, 해당 브랜치 전용 프로젝트 채널을 만들 수 있다.

예를 들어 결제 기능을 개발한다고 해보자.

feature/payment-api라는 브랜치가 만들어지면 관련 채널에서 다음 활동이 함께 진행된다.

기능 요구사항 논의
코드 변경
AI 에이전트의 분석
테스트 결과
코드 리뷰
수정 요청
최종 승인
병합 결정

기존 환경에서는 이 정보가 Slack, GitHub Pull Request, 자동화 로그 등에 나뉘어 저장된다.

Buzz에서는 코드와 대화가 같은 프로젝트 흐름 안에 들어간다.

나중에 문제가 발생했을 때 단순히 “어떤 코드가 변경됐는가”만 보는 것이 아니라, “왜 이 코드를 변경했는가”까지 확인할 수 있다.

AI 에이전트 입장에서도 큰 차이가 생긴다.

코드만 읽는 것이 아니라 코드가 작성된 배경, 관련 대화, 테스트 결과, 리뷰 의견을 함께 이해할 수 있기 때문이다.

대화와 코드가 하나의 조직 기억이 된다

기업이 AI를 업무에 적용할 때 가장 어려운 문제 중 하나는 정보가 분산돼 있다는 것이다.

AI가 제대로 답변하려면 여러 장소에서 자료를 가져와야 한다.

Slack의 대화
GitHub의 코드
Notion의 문서
Jira의 이슈
CI/CD 테스트 기록

각 서비스의 데이터를 수집하고, 검색 시스템에 넣고, 서로 연결해야 한다.

Buzz는 처음부터 대화와 코드 활동을 같은 이벤트 구조로 저장하는 방향을 택했다.

팀 메시지, 코드 변경, 리뷰 승인, 워크플로 실행, AI 작업 등이 하나의 연속된 기록으로 남는다.

예를 들어 서비스 장애가 발생했을 때 AI에게 이렇게 물을 수 있다.

이 오류가 과거에도 발생한 적이 있는가?

AI는 단순히 문서에서 비슷한 문장을 찾는 데 그치지 않는다.

과거의 장애 대화, 당시 수정된 코드, 테스트 결과, 작업한 사람, 재발 방지 조치까지 함께 찾아낼 수 있다.

이렇게 축적된 기록은 회사의 조직 기억이 된다.

사람이 퇴사하거나 담당자가 바뀌어도 프로젝트가 어떤 과정을 거쳐 현재 모습이 됐는지 추적할 수 있다.

모든 작업에 서명이 붙는다

Buzz는 Nostr 프로토콜의 이벤트 구조를 활용한다.

메시지 작성, 코드 변경, 리뷰 승인, 워크플로 실행과 같은 활동이 이벤트로 기록되고, 각 이벤트에는 작업을 수행한 주체의 암호화 서명이 붙는다.

이를 통해 다음 내용을 확인할 수 있다.

누가 작업했는가
사람인가, AI 에이전트인가
어떤 권한으로 작업했는가
어떤 요청에서 작업이 시작됐는가
어떤 코드가 변경됐는가
누가 검토하고 승인했는가

AI가 실제 코드를 수정하고 업무를 수행하는 환경에서는 결과만큼이나 과정이 중요하다.

AI가 어떤 정보를 참고했는지, 어떤 권한을 사용했는지, 최종적으로 누가 승인했는지가 명확하게 남아야 한다.

Buzz는 AI 에이전트 시대의 협업에서 감사 가능성과 책임 추적이 중요한 요소가 될 것임을 보여준다.

정말 탈중앙화된 플랫폼일까

Buzz는 오픈소스와 자기주권적인 운영 방식을 강조한다.

기업이나 조직은 Buzz를 자신의 서버에 설치할 수 있다. 대화, 코드, 파일과 같은 데이터를 외부 SaaS 기업에 맡기지 않고 직접 관리하는 것도 가능하다.

그러나 이를 완전한 P2P 탈중앙 네트워크로 이해해서는 안 된다.

현재 Buzz의 각 커뮤니티는 하나의 중앙 릴레이 서버를 중심으로 작동한다. 사용자의 읽기와 쓰기, 검색, 이벤트 처리도 해당 릴레이가 담당한다.

릴레이끼리 데이터를 자동으로 교환하거나 복제하는 완전한 분산형 구조는 아니다.

따라서 Buzz가 말하는 탈중앙화는 다음 의미에 더 가깝다.

특정 SaaS 기업에 종속되지 않는다.
조직이 자체 서버를 운영할 수 있다.
조직이 자신의 데이터와 도메인을 소유한다.
사용자가 암호화 신원을 사용할 수 있다.
소스 코드가 공개돼 있다.

즉, 시스템 내부가 완전히 탈중앙화돼 있다기보다, 여러 조직이 각자의 서버를 소유할 수 있는 분산 배포형 오픈소스 플랫폼에 가깝다.

아직은 완성된 기업용 제품이 아니다

Buzz는 흥미로운 비전을 제시하지만, 현재는 개발 단계에 있는 프로젝트다.

팀 채널, 개인 메시지, 공동 캔버스, 검색, 감사 로그, 데스크톱 앱, Git 호스팅, 워크플로와 같은 기능은 구현돼 있다.

반면 모바일 앱, 푸시 알림, 일부 승인 워크플로와 고급 에이전트 기능은 계속 개발되고 있다.

Slack, GitHub, Notion, Jenkins처럼 오랫동안 검증된 서비스를 한 번에 대체할 만큼 안정적인지는 아직 확인이 필요하다.

자체 호스팅 방식에도 책임이 따른다.

조직은 직접 서버를 운영하고, 보안을 관리하고, 데이터를 백업하고, 장애와 업데이트에 대응해야 한다.

오픈소스라는 이유만으로 운영 비용과 관리 부담까지 사라지는 것은 아니다.

Buzz가 보여주는 것은 제품보다 조직의 변화다

[Inference] Buzz의 의미는 단순히 새로운 협업 서비스 하나가 등장했다는 데 있지 않다.

더 중요한 변화는 AI를 바라보는 관점에 있다.

현재 기업은 AI를 직원이 사용하는 도구로 본다.

직원
→ AI에게 질문
→ AI가 답변
→ 직원이 실제 업무 수행

Buzz가 지향하는 구조에서는 AI가 업무 과정 안으로 직접 들어온다.

사람과 AI가 같은 프로젝트에 참여
→ AI가 대화와 코드를 확인
→ AI가 작업 수행
→ 사람이 검토하고 승인
→ 전체 과정이 기록으로 보존

[Inference] 앞으로의 회사에서는 AI가 단순히 생산성을 높이는 프로그램이 아니라, 특정 역할을 맡아 반복적으로 일하는 디지털 구성원이 될 가능성이 있다.

한 AI는 버그를 분석하고, 다른 AI는 코드를 리뷰할 수 있다. 또 다른 AI는 문서를 정리하고 프로젝트 진행 상황을 요약할 수 있다.

사람은 모든 작업을 직접 처리하기보다, 목표와 권한을 설정하고 결과를 검토하는 역할로 이동할 수 있다.

이때 회사에 필요한 것은 더 강력한 챗봇 하나가 아니다.

AI가 어떤 정보에 접근할 수 있는지, 어떤 행동을 할 수 있는지, 누가 결과를 승인하는지 관리할 수 있는 새로운 업무 시스템이다.

Buzz는 바로 그 문제를 먼저 설계하려는 시도다.

AI 시대의 협업 도구가 갖춰야 할 조건

[Inference] Buzz의 구조를 통해 앞으로의 AI 협업 플랫폼에 필요한 조건을 정리해볼 수 있다.

첫째, AI 에이전트마다 독립적인 신원이 필요하다.

여러 AI가 같은 계정과 권한을 공유하면 어떤 에이전트가 어떤 작업을 했는지 구분하기 어렵다.

둘째, 최소 권한 원칙이 필요하다.

AI가 필요 이상의 대화와 코드에 접근하지 못하도록 프로젝트 단위의 권한을 부여해야 한다.

셋째, 모든 실행 과정이 기록돼야 한다.

AI가 어떤 요청을 받고, 어떤 자료를 참고하고, 무엇을 변경했는지 추적할 수 있어야 한다.

넷째, 중요한 작업에는 사람의 승인이 남아야 한다.

AI가 작업을 수행하더라도 배포, 결제, 데이터 삭제처럼 위험도가 높은 행동은 사람이 검토하는 구조가 필요하다.

다섯째, 대화와 실행 기록이 분리되지 않아야 한다.

AI가 업무 맥락을 이해하려면 코드뿐 아니라 그 코드가 만들어진 이유까지 볼 수 있어야 한다.

AI 팀원이 출근하는 시대

Buzz가 성공적으로 정착할지는 아직 알 수 없다.

기존 협업 도구를 대체하기에는 부족한 기능이 있고, 자체 서버 운영에 따른 부담도 존재한다. Block 내부에서 효과적으로 사용되더라도 다른 기업에서도 같은 방식이 통할지는 더 지켜봐야 한다.

그러나 Buzz가 던진 문제는 분명하다.

AI가 실제 업무를 수행하기 시작하면 회사는 더 이상 AI를 단순한 플러그인이나 채팅 기능으로만 관리할 수 없다.

AI에게도 신원이 필요하고, 권한이 필요하며, 활동 기록과 책임 범위가 필요하다.

사람과 AI가 함께 일하는 회사는 단순히 기존 업무 도구에 AI 버튼 하나를 추가한 모습이 아닐 가능성이 크다.

대화, 코드, 권한, 실행, 승인, 기록이 모두 연결된 새로운 업무 환경이 필요하다.

Buzz는 그 미래를 완성한 제품은 아니다.

하지만 AI가 도구의 자리를 넘어 팀원의 자리로 이동할 때 회사의 운영체제는 어떻게 바뀌어야 하는가라는 질문을 가장 구체적으로 보여주는 사례 중 하나다.

Buzz — Your people, your agents, your project — all in one place.

Come test the early stages with us.

buzz.xyz

파라미터 대신 ‘작업의 지평선’을 확장한 AI 모델 Agents-A1

행복한 수지아빠 — Tue, 21 Jul 2026 13:48:33 +0900

35B 모델이 거대 AI를 따라잡는 방법

인공지능 모델의 발전은 오랫동안 하나의 방향으로 설명됐다.

더 많은 데이터를 학습하고, 더 많은 연산을 투입하고, 더 많은 파라미터를 가진 모델을 만든다. 모델이 커질수록 더 복잡한 문제를 해결할 수 있다는 것이 대규모 언어 모델의 기본적인 성장 공식이었다.

그런데 InternScience가 공개한 Agents-A1은 조금 다른 질문을 던진다.

모델의 크기를 계속 키우는 대신, AI가 한 번에 수행할 수 있는 작업의 길이를 늘리면 어떨까?

Agents-A1의 기술 보고서 제목은 이 질문을 그대로 담고 있다.

“Scaling the Horizon, Not the Parameters”

파라미터가 아니라 ‘지평선’을 확장한다는 의미다. 여기서 지평선, 즉 Horizon은 AI가 하나의 목표를 해결하기 위해 계획하고, 검색하고, 도구를 사용하고, 결과를 확인하고, 실패를 수정하는 전체 작업 길이를 뜻한다.

Agents-A1은 총 35B 규모의 Mixture-of-Experts 모델로, 장시간 검색, 엔지니어링, 과학 연구, 복합 지시 이행, 도구 호출에 특화되어 있다. 공식 프로젝트는 최대 256K 컨텍스트와 여섯 가지 에이전트 평가 영역을 제시한다.

Agents-A1은 무엇이 다른가

일반적인 챗봇 모델은 사용자의 질문을 받은 뒤 답변을 생성한다.

질문 → 추론 → 답변

Agents-A1이 목표로 하는 작업은 조금 더 길다.

목표 이해
→ 문제 분해
→ 검색 도구 실행
→ 검색 결과 확인
→ 추가 정보 판단
→ 코드 실행
→ 오류 확인
→ 전략 수정
→ 결과 검증
→ 최종 답변

즉, 좋은 문장을 만드는 것뿐 아니라 여러 단계의 행동을 이어가며 실제 작업을 끝내는 능력을 강화한 모델이다.

공식 프로젝트는 Agents-A1이 복잡한 목표를 실행 가능한 하위 단계로 나누고, 중간 결과에 따라 전략을 수정하며, API·검색 엔진·코드 인터프리터 같은 외부 도구를 호출할 수 있도록 설계됐다고 설명한다.

이 차이는 생각보다 크다.

일반 모델이 “이 문제를 해결하려면 웹 검색과 데이터 분석이 필요합니다”라고 설명하는 데 그친다면, 에이전트 모델은 검색 도구를 호출하고, 결과를 비교하고, 필요한 계산을 수행한 뒤 최종 결론까지 도달해야 한다.

Agents-A1은 이처럼 오래 이어지는 작업 과정 자체를 학습 대상으로 삼았다.

평균 4만 5천 토큰의 작업 과정을 학습하다

Agents-A1 연구진은 외부 지식, 행동, 관찰 결과, 검증 결과를 연결하는 장기 작업 인프라를 구축했다.

이 인프라에서는 단순한 질문과 정답만 저장하지 않는다.

AI가 어떤 행동을 선택했는지, 도구를 실행한 뒤 무엇을 관찰했는지, 결과가 맞았는지, 다음 행동을 어떻게 수정했는지까지 하나의 궤적으로 만든다. 연구진이 구축한 에이전트 궤적의 평균 길이는 약 45K 토큰이다.

학습은 세 단계로 진행됐다.

첫 번째는 여러 영역의 에이전트 행동을 폭넓게 학습하는 지도 미세조정이다.

두 번째는 검색, 과학, 엔지니어링 등 각 영역에 특화된 교사 모델을 별도로 훈련하는 단계다.

세 번째는 여러 교사 모델의 능력을 하나의 모델로 이전하는 다중 교사 온폴리시 증류다. 연구진은 이를 통해 서로 다른 여섯 가지 에이전트 능력을 하나의 35B 모델에 통합했다고 설명한다.

쉽게 표현하면 다음과 같다.

검색 전문 교사
과학 연구 전문 교사
엔지니어링 전문 교사
도구 사용 전문 교사
지시 이행 전문 교사
        ↓
Agents-A1 하나로 통합

모델을 무작정 크게 만드는 대신, 각 분야에서 길고 복잡한 작업을 수행한 경험을 효율적으로 증류한 것이다.

35B 모델이 1조 파라미터급과 경쟁한다는 의미

Agents-A1을 소개하는 문구 가운데 가장 눈에 띄는 표현은 “35B 모델로 1조 파라미터급 성능에 도달했다”는 주장이다.

이 표현은 주의해서 해석해야 한다.

Agents-A1이 모든 영역에서 1조 파라미터급 모델보다 뛰어나다는 뜻은 아니다. 공식 평가표를 보면 특정 장기 작업과 과학 연구, 복합 지시 이행에서 매우 강한 결과를 기록한 반면, 일부 코딩·머신러닝·검색 벤치마크에서는 더 큰 상용 모델보다 낮은 점수를 기록했다.

공식 모델 카드가 보고한 대표 결과는 다음과 같다.

SEAL-0: 56.36
GAIA: 96.04
BrowseComp: 75.51
FrontierScience-Olympiad: 79.0
FrontierScience-Research: 40.0
IFBench: 80.61
IFEval: 94.82

특히 SEAL-0, HiPhO, FrontierScience, IFBench 등에서는 비교 대상 대형 모델보다 높은 결과가 보고됐다. 반면 SciCode에서는 Agents-A1이 44.33, GPT-5.5가 56.1이었고, MLE-Lite에서는 Agents-A1이 43.94, GPT-5.5가 72.73이었다. BrowseComp 역시 Agents-A1의 75.51보다 비교 대상 대형 모델들의 점수가 더 높았다.

따라서 정확한 표현은 다음에 가깝다.

Agents-A1은 모든 능력에서 초거대 모델을 대체하는 모델이 아니라, 일부 장기 에이전트 작업에서 훨씬 큰 모델과 경쟁할 수 있는 효율적인 특화 모델이다.

이 점이 Agents-A1의 진짜 의미다.

일반 추론 모델과는 무엇이 다른가

추론 모델은 어려운 수학 문제나 논리 문제를 해결하기 위해 내부 계산을 길게 수행한다.

문제 → 긴 내부 추론 → 답변

에이전트 모델은 내부 추론과 함께 외부 환경을 활용한다.

문제
→ 계획
→ 도구 호출
→ 결과 관찰
→ 계획 수정
→ 추가 도구 호출
→ 검증
→ 답변

즉, 추론 모델의 중심이 생각의 깊이라면 에이전트 모델의 중심은 생각과 행동의 연결이다.

Agents-A1은 함수 호출과 외부 도구 연동을 기본적으로 지원한다. 공식 실행 예제에서는 검색·코드 실행·API 호출에 사용할 수 있는 도구 호출 파서가 제공되며, SGLang과 vLLM을 통해 OpenAI 호환 API 서버로 실행할 수 있다.

다만 모델 하나를 실행했다고 해서 자동으로 웹 검색이나 파일 수정이 가능한 것은 아니다.

Agents-A1은 어떤 도구를 사용할지 판단하는 두뇌에 가깝다. 실제 검색, 브라우저 조작, 터미널 실행, 파일 읽기와 쓰기는 별도의 에이전트 런타임이 담당해야 한다.

Agents-A1
    ↓ 도구 호출 요청
에이전트 프레임워크
    ↓
웹 검색·브라우저·Python·터미널·파일 시스템
    ↓ 실행 결과
Agents-A1
    ↓ 다음 행동 결정

따라서 Agents-A1의 성능을 제대로 활용하려면 단순 채팅 UI보다 도구가 연결된 실행 환경이 중요하다.

장문맥 모델과 장기 에이전트 모델은 다르다

Agents-A1은 공식 실행 예제에서 최대 262,144토큰의 컨텍스트 길이를 지원한다. 이미지 입력을 포함하는 멀티모달 모델이며, 텍스트 전용 실행 시에는 비전 인코더를 제외해 KV 캐시 공간을 확보하는 옵션도 제공된다.

그러나 긴 컨텍스트를 지원한다고 해서 반드시 긴 작업을 잘 수행하는 것은 아니다.

긴 문서를 한꺼번에 입력할 수 있는 능력과 여러 단계의 작업 목표를 끝까지 유지하는 능력은 서로 다르다.

일반 장문맥 모델은 긴 자료를 읽을 수 있어도 다음과 같은 문제를 보일 수 있다.

이미 조사한 내용을 반복한다.
중간에 원래 목표를 잊는다.
이전 도구의 오류를 반영하지 못한다.
여러 지시 조건 가운데 일부를 놓친다.
잘못된 방향으로 진행하면서도 작업을 계속한다.

Agents-A1이 강조하는 것은 단순한 컨텍스트 크기가 아니라, 긴 행동 궤적 안에서 목표·관찰·검증 결과를 유지하는 능력이다.

이것이 논문 제목에서 말하는 Horizon Scaling의 핵심이다.

Agents-A1의 장점

1. 중형 모델로 구현한 강력한 장기 작업 능력

35B급 모델이 일부 장기 검색과 과학 연구 벤치마크에서 훨씬 큰 모델과 경쟁한 것은 의미가 있다.

초거대 모델을 직접 운영하기 어려운 연구소나 기업에도 비교적 현실적인 에이전트 모델 선택지가 생겼기 때문이다.

2. 도구 호출을 전제로 설계된 모델

Agents-A1은 검색, API, 코드 인터프리터, 외부 작업 환경과 연동하는 함수 호출을 지원한다. 단순 질의응답보다 조사·분석·실행을 반복하는 워크플로에 적합하다.

3. 과학·연구형 작업에서 강한 결과

공식 평가에서는 FrontierScience-Research, FrontierScience-Olympiad, HiPhO 같은 과학 연구형 평가에서 강한 성능이 보고됐다. 특히 FrontierScience-Research에서는 비교표에 포함된 대형 모델보다 높은 점수를 기록했다.

4. 복잡한 지시 조건을 잘 유지

IFEval과 IFBench에서 높은 점수가 보고됐다. 이는 단순히 질문에 답하는 것보다 출력 형식, 금지 조건, 단계별 요구사항처럼 여러 제약을 동시에 지켜야 하는 작업에서 중요하다.

5. 오픈소스 생태계

모델 가중치와 일부 평가 코드, 기술 보고서가 공개돼 있다. 라이선스는 Apache 2.0이며, Hugging Face Transformers, SGLang, vLLM 형식으로 사용할 수 있다. 공식 모델 카드에는 llama.cpp, Ollama, LM Studio 등에서 사용할 수 있는 양자화 모델 탐색 경로도 제공된다.

6. 4B 경량 모델도 제공

InternScience는 2026년 7월 14일 Agents-A1-4B를 공개했다. 공식 결과에서는 4B 모델도 일부 검색·과학·지시 이행 벤치마크에서 비슷한 크기의 기본 모델보다 높은 성능을 기록했다.

35B 모델이 서버나 고성능 워크스테이션용이라면, 4B 모델은 개인용 로컬 에이전트 실험에 더 가까운 선택지다.

Agents-A1의 단점과 주의할 점

1. 모든 분야에서 최고 성능은 아니다

Agents-A1은 장기 검색과 과학 연구, 복합 지시 이행에 강하지만 모든 코딩·엔지니어링 작업에서 최고는 아니다.

공식 평가에서도 SciCode, MLE-Lite, HLE with tools, BrowseComp 등 일부 항목은 대형 프런티어 모델보다 낮았다.

따라서 “35B 모델이 1조 파라미터 모델을 완전히 대체했다”는 식의 해석은 과장에 가깝다.

2. 벤치마크와 실제 업무 사이에는 차이가 있다

공식 평가는 공개된 에이전트 평가 프레임워크를 통해 일부 재현이 가능하다. 다만 벤치마크 성능이 기업 내부 시스템, 브라우저 자동화, 복잡한 파일 작업, 장시간 코딩 프로젝트에서 동일하게 나타난다고 단정할 수는 없다. 공식 모델 카드 역시 비교 대상 모델의 기존 보고값과 자체 평가값을 함께 사용했다고 설명한다.

도입 전에는 실제 업무 데이터와 도구 환경을 이용한 별도 검증이 필요하다.

3. 모델만으로는 에이전트가 완성되지 않는다

Agents-A1은 도구를 선택하고 다음 행동을 결정할 수 있지만, 실제 도구 실행 시스템은 별도로 구축해야 한다.

권한 관리, 재시도, 브라우저 상태, 오류 복구, 비용 제한, 사용자 승인, 로그 기록 같은 기능은 에이전트 프레임워크와 애플리케이션이 담당해야 한다.

4. 장기 작업은 비용과 시간이 커진다

긴 작업은 짧은 질문보다 더 많은 토큰과 도구 호출을 사용한다.

컨텍스트가 길어질수록 첫 응답까지 걸리는 시간이 증가하고, 검색과 코드 실행을 반복하면 전체 작업 시간도 길어진다. “더 작은 모델”이 반드시 “더 저렴한 작업”을 의미하지는 않는다. 에이전트가 얼마나 많은 단계를 수행하는지도 전체 비용을 결정한다.

5. 로컬 실행에는 여전히 높은 사양이 필요하다

35B급 모델은 양자화를 사용하더라도 일반 노트북에서 가볍게 실행하는 모델은 아니다.

개인 PC에서는 GGUF나 다른 양자화 버전을 사용하거나, 더 작은 Agents-A1-4B를 선택하는 편이 현실적이다. 원본 모델을 긴 컨텍스트와 비전 기능까지 포함해 서비스하려면 충분한 GPU 메모리와 서빙 환경이 필요하다.

어떤 작업에 적합할까

Agents-A1이 잘 맞을 가능성이 높은 작업은 다음과 같다.

여러 웹사이트를 조사하는 심층 리서치
논문 검색과 근거 비교
코드를 작성하고 실행하고 수정하는 반복 작업
과학·공학 분야의 도구 기반 문제 해결
여러 제약 조건이 포함된 복잡한 보고서 작성
API를 연속 호출하는 업무 자동화
긴 프로젝트를 단계별로 수행하는 연구 에이전트
이미지와 문서를 함께 분석하는 멀티모달 작업

반대로 간단한 번역, 짧은 요약, 일상 대화, 단순 질의응답처럼 한 번의 응답으로 끝나는 작업에서는 Agents-A1의 장점이 크게 드러나지 않을 수 있다.

이런 작업에는 더 작은 4B·7B급 모델이 빠르고 효율적일 수 있다.

Agents-A1이 보여주는 새로운 방향

Agents-A1의 가장 중요한 성과는 특정 벤치마크 점수 하나가 아니다.

이 모델이 보여주는 것은 모델 성능을 키우는 방법이 파라미터 증가만은 아니라는 가능성이다.

앞으로의 AI 경쟁은 다음과 같이 바뀔 수 있다.

더 큰 모델
→ 더 긴 작업을 수행하는 모델

더 많은 지식
→ 지식을 찾고 검증하는 능력

더 좋은 답변
→ 실제 도구를 사용해 일을 끝내는 능력

물론 Agents-A1 하나로 초거대 모델의 시대가 끝난 것은 아니다.

복잡한 코딩, 범용 추론, 창작, 세계 지식, 안정성 등에서는 대형 프런티어 모델이 여전히 강하다. Agents-A1의 공식 결과에서도 영역별 성능 차이가 분명하게 나타난다.

그럼에도 Agents-A1은 중요한 질문을 남긴다.

AI의 능력을 키우기 위해 모델 자체를 계속 크게 만들어야 할까?
아니면 작은 모델이 더 오래 생각하고, 더 많은 도구를 사용하고, 더 긴 작업을 경험하도록 만드는 편이 효과적일까?

Agents-A1은 후자의 가능성을 보여주는 모델이다.

작은 몸집으로 모든 문제를 해결하는 모델은 아니다. 하지만 검색하고, 실행하고, 관찰하고, 수정하며 끝까지 작업을 이어가는 능력에서는 기존 중형 오픈 모델보다 한 단계 진화한 방향을 제시한다.

AI가 단순히 답을 생성하는 도구에서 실제 업무를 수행하는 에이전트로 이동하는 시점에, Agents-A1이 주목받는 이유도 바로 여기에 있다.

한 줄 정리

Agents-A1은 파라미터 수를 무작정 늘리는 대신, AI가 계획하고 도구를 사용하며 작업을 이어가는 ‘지평선’을 확장한 35B 오픈 에이전트 모델이다.

모든 분야에서 초거대 모델을 이기는 것은 아니지만, 장기 검색·과학 연구·복합 지시 이행에서는 모델 크기 대비 매우 강한 성능을 보여준다. 앞으로 로컬 AI와 기업용 에이전트가 어떤 방향으로 발전할지를 보여주는 흥미로운 사례다.