# reopt architecture

> An AI-native system design methodology published by reopt Inc. It gives teams building AI agent products a four-layer model (Module → Agent → Collaboration → Governance), the OCLS operating loop (OWN → CONTRACT → LAYER → SHARPEN), eight architecture patterns, a GOVERNANCE.md specification with seven lint rules, and installable Claude Code skills. Every page is free, needs no account, and is published in Korean (default) and English.

The site is a reference manual, not a product or an API. There is nothing to sign up for and no endpoint to call — the value is the written methodology, the pattern catalog, and the copyable governance artifacts.

## When to use this site

Reach for these documents when a question is about **structuring an AI agent product so it does not collapse as it grows**. Concretely:

- **Who owns an outcome an agent produced?** → the four-layer model and the `responsibility-partitioning` / `decision-traceability` patterns.
- **What contract should a module or an agent expose, and when should it refuse?** → the `module-contract` pattern and the CONTRACT phase of OCLS.
- **How do several agents collaborate without stepping on each other?** → the collaboration-category patterns and the Collaboration layer.
- **How do we write down governance a team and a linter can both check?** → the GOVERNANCE.md specification, its canonical section order, and the seven lint rules.
- **Our AI product ships fast but keeps breaking. What is accumulating?** → agentic debt: its four types and the loop phase each one comes from.
- **Which structural work matters at our stage?** → the five-stage evolution path and the interactive product assessment.
- **We need a design review or a sprint checklist for an agent system.** → the checklist, filterable by layer, OCLS phase, and perspective.
- **We want these rules enforced inside Claude Code.** → the skills, copied into `.claude/skills`, `.claude/commands`, or `.claude/agents`.

Do **not** reach for this site for framework or SDK usage (LangChain, MCP server code, model API parameters). It deliberately stops at structure and judgment, and names no framework as a requirement.

## Access and cost

- **Free, no account, no API key.** Every document is public and served without authentication, sign-up, rate limit, or paywall. There is nothing to request access to and no sales step.
- **No sandbox needed** — there is no API to call against, so there is no test environment to provision. Fetch any URL below directly.
- **Reuse:** quoting and referencing with attribution is welcome. Reproducing the site's visual design or layout for another product is not.

## Formats

- Every page has a Markdown twin: append `.md` to any path (`https://architecture.reopt.ai/ko/patterns/module-contract.md`), or send `Accept: text/markdown` to the HTML URL. Each Markdown document opens with a YAML frontmatter block carrying title, description, canonical, language, and last-updated.
- Locales: ko, en (default `ko`). Swap the leading path segment: `/ko/patterns` ↔ `/en/patterns`.
- Machine indexes: [ai-catalog.json](https://architecture.reopt.ai/.well-known/ai-catalog.json) (Agentic Resource Discovery), [sitemap.xml](https://architecture.reopt.ai/sitemap.xml), [RSS](https://architecture.reopt.ai/rss.xml).

## Developer resources

This is a methodology reference, not a hosted service — there is no REST API, OpenAPI document, SDK, or auth flow, and none is planned. What a developer or a coding agent actually consumes here:

- **reopt architecture skills for Claude Code** — 11 SKILL.md / command / sub-agent files, copied into `.claude/skills`, `.claude/commands`, or `.claude/agents`. Browse at https://architecture.reopt.ai/ko/skills.md; each one is listed individually below and in the ai-catalog.
- **GOVERNANCE.md specification** — canonical section order, machine-readable YAML frontmatter, and seven lint rules a reviewer or CI can enforce: https://architecture.reopt.ai/ko/governance.md
- **Governance lint rules** — the rule catalog with severity and target, plus a paste-in checker: https://architecture.reopt.ai/ko/governance/lint.md
- **Markdown document API** — the `.md` suffix and `Accept: text/markdown` negotiation described above; the full URL list is in [sitemap.xml](https://architecture.reopt.ai/sitemap.xml).
- **Source repository** — the site, the skills, and the content modules: https://github.com/reopt-ai/reopt-architecture

## Start here

- [Home](https://architecture.reopt.ai/ko.md): The thesis, the five-step methodology, and the evolution path in one page.
- [Architecture](https://architecture.reopt.ai/ko/architecture.md): The four-layer model, agentic debt, design principles, and how this relates to existing methodologies.
- [Pattern catalog](https://architecture.reopt.ai/ko/patterns.md): Eight patterns grouped by responsibility, collaboration, and governance.
- [GOVERNANCE.md](https://architecture.reopt.ai/ko/governance.md): The one-page structural contract: canonical section order, machine-readable frontmatter, and seven lint rules.
- [Product assessment](https://architecture.reopt.ai/ko/assessment.md): Scores a product on engineering and business attributes, then returns pattern priorities, tensions, and a tailored checklist.
- [Checklist](https://architecture.reopt.ai/ko/checklist.md): Design-review questions filterable by layer, OCLS phase, and perspective.
- [Glossary](https://architecture.reopt.ai/ko/glossary.md): Definitions the rest of the site relies on — agent, contract, loop, agentic debt, OCLS.
- [About](https://architecture.reopt.ai/ko/about.md): Background of the methodology, the author, and the academic references behind it.

## Patterns

- [Responsibility Partitioning](https://architecture.reopt.ai/ko/patterns/responsibility-partitioning.md): 결과를 소유할 주체와 책임 경계를 명확히 정의한다. (responsibility, OWN)
- [Module Contract](https://architecture.reopt.ai/ko/patterns/module-contract.md): 실행 단위의 조건, 권한, 실패 경로를 계약으로 선언한다. (responsibility, CONTRACT)
- [Context Routing](https://architecture.reopt.ai/ko/patterns/context-routing.md): 각 주체에 필요한 정보만 전달되도록 정보 흐름을 설계한다. (collaboration, LAYER)
- [State and Memory Control](https://architecture.reopt.ai/ko/patterns/state-and-memory-control.md): 단기 상태와 장기 기억을 분리해 정보 누수와 혼선을 방지한다. (collaboration, LAYER)
- [Evaluation and Guardrails](https://architecture.reopt.ai/ko/patterns/evaluation-and-guardrails.md): 허용되는 판단과 위험한 판단을 평가 기준과 안전 규칙으로 구분한다. (governance, SHARPEN)
- [Human Approval](https://architecture.reopt.ai/ko/patterns/human-approval.md): 고비용·고위험·고영향 의사결정은 인간 승인 흐름 안에 둔다. (governance, SHARPEN)
- [Cost Control](https://architecture.reopt.ai/ko/patterns/cost-control.md): 토큰 예산, 모델 선택, 호출 빈도를 구조적으로 관리하여 비용 곡선을 통제한다. (collaboration, LAYER)
- [Decision Traceability](https://architecture.reopt.ai/ko/patterns/decision-traceability.md): 판단 근거, 선택 사유, 협업 경로를 구조화된 로그로 남긴다. (governance, SHARPEN)

## Environment

- [Business](https://architecture.reopt.ai/ko/environment/business.md): Turning a loop's token spend into unit economics, and the three paths that keep a loop alive.
- [Token strategy](https://architecture.reopt.ai/ko/environment/token-strategy.md): Three token modes and how staffing and technical gain shift by stage.
- [Data](https://architecture.reopt.ai/ko/environment/data.md): The data flywheel — traces, evaluations, and learning signals that make a loop improve rather than merely persist.

## Articles

- [토큰 전략 — 효율·밸런스·공격적, 그리고 인력 배분](https://architecture.reopt.ai/ko/articles/loop-token-strategy.md): 토큰을 아끼는 것과 태우는 것은 둘 다 전략이다. 같은 루프를 효율·밸런스·공격적 세 모드로 다르게 운영하고, 비즈니스 상황과 진화 단계에 맞춰 모드와 인력을 배분한다. 토큰 사용을 기술적 선택으로 정리한다. (2026-06-16)
- [데이터 플라이휠 — 루프를 지속이 아니라 발전시키는 것](https://architecture.reopt.ai/ko/articles/loop-data-flywheel.md): 돈은 루프를 돌리고 토큰은 연산하지만, 다음 바퀴를 이전보다 낫게 만드는 것은 운영이 쌓은 데이터다. trace·평가·학습 신호 세 자산으로 플라이휠을 돌리고, 데이터를 모델 밖 자산으로 두어 주권을 지킨다. (2026-06-16)
- [루프의 비즈니스 경제학 — 토큰으로 버는 법과 버티는 법](https://architecture.reopt.ai/ko/articles/loop-business-economics.md): 비용을 통제하는 것만으로는 루프가 지속되지 않는다. 토큰 단가와 마진으로 수익 구조를 보고, 자급·투자·생태계 세 경로 중 어떻게 버틸지를 고른다. 각 경로의 현실적 문제와 최고·최악 시나리오를 reopt architecture의 진화 단계 언어로 정리한다. (2026-06-16)
- [모델 주권과 인간 주도성 — 4계층 위에서의 두 축](https://architecture.reopt.ai/ko/articles/model-sovereignty-and-human-agency.md): 모델은 교체되고 컴퓨트는 흔해진다. 그래서 통제할 대상은 모델이 아니라 모델 위에 쌓는 학습 루프이고, 그 루프를 향하게 하는 것은 인간의 방향이다. reopt architecture의 4계층·8패턴·OCLS 언어로 두 축을 설계로 옮긴다. (2026-06-15)
- [Claude Code로 reopt architecture 5단계 실행하기](https://architecture.reopt.ai/ko/articles/claude-code-with-reopt-architecture.md): 진단→정의→순환→실행→평가 방법론을 Claude Code의 CLAUDE.md 자동 로드, slash command, sub-agent, skill에 매핑하여 실제 레포에 적용하는 실전 가이드. (2026-04-17)
- [Reopt Agentic Governance 구현기: 진단에서 시스템까지](https://architecture.reopt.ai/ko/articles/reopt-agentic-patterns-in-production.md): 8개 AI 에이전트를 운영하는 프로덕션 SaaS에서 reopt architecture 원칙으로 거버넌스 공백을 진단하고, 범용 감사 로깅, 영속적 승인 기록, MCP 추적·속도 제한, 에이전트 제약, Admin 대시보드까지 구현한 과정. (2026-04-15)
- [opt-harness를 활용한 Agent Catalog 아키텍처 구현](https://architecture.reopt.ai/ko/articles/opt-harness-agent-catalog-architecture.md): 설계 거버넌스 하네스 패키지 @reopt-ai/opt-harness를 사용하여 Agent Catalog의 아키텍처 원칙을 실제 제품 구현으로 옮기는 실전 사례. (2026-04-14)

## Skills — individual files

- [reopt-responsibility-partitioning](https://architecture.reopt.ai/ko/skills/reopt-responsibility-partitioning.md): 여러 에이전트가 협업할 때 책임 경계를 분할하는 패턴을 적용한다. → install under .claude/skills/
- [reopt-module-contract](https://architecture.reopt.ai/ko/skills/reopt-module-contract.md): 모듈의 입출력·거절 조건·실패 모드를 계약으로 선언한다. → install under .claude/skills/
- [reopt-context-routing](https://architecture.reopt.ai/ko/skills/reopt-context-routing.md): 각 주체에 필요한 컨텍스트만 전달되도록 흐름을 설계한다. → install under .claude/skills/
- [reopt-state-and-memory-control](https://architecture.reopt.ai/ko/skills/reopt-state-and-memory-control.md): 단기 상태와 장기 기억을 분리해 정보 누수와 혼선을 방지한다. → install under .claude/skills/
- [reopt-evaluation-and-guardrails](https://architecture.reopt.ai/ko/skills/reopt-evaluation-and-guardrails.md): 허용 판단과 위험 판단을 평가 기준과 안전 규칙으로 구분한다. → install under .claude/skills/
- [reopt-human-approval](https://architecture.reopt.ai/ko/skills/reopt-human-approval.md): 고비용·고위험·고영향 결정을 인간 승인 흐름 안에 둔다. → install under .claude/skills/
- [reopt-cost-control](https://architecture.reopt.ai/ko/skills/reopt-cost-control.md): 토큰 예산·모델 선택·호출 빈도를 구조적으로 관리해 비용을 통제한다. → install under .claude/skills/
- [reopt-decision-traceability](https://architecture.reopt.ai/ko/skills/reopt-decision-traceability.md): 판단 근거·선택 사유·협업 경로를 구조화된 로그로 남긴다. → install under .claude/skills/
- [/ocls-review](https://architecture.reopt.ai/ko/skills/ocls-review.md): 현재 변경사항을 OCLS 4단계로 검증하고 위반 항목의 패치 제안을 생성한다. → install under .claude/commands/
- [/debt-audit](https://architecture.reopt.ai/ko/skills/debt-audit.md): 최근 스프린트의 부채 4종을 감사하고 GOVERNANCE.md 갱신안을 생성한다. → install under .claude/commands/
- [governance-reviewer](https://architecture.reopt.ai/ko/skills/governance-reviewer.md): PR·브랜치 변경을 OCLS·8패턴 관점으로 리뷰하는 sub-agent. → install under .claude/agents/

## Site information

- [Contact](https://architecture.reopt.ai/ko/contact.md): Channels for corrections, pattern proposals, citation requests, and collaboration.
- [Privacy](https://architecture.reopt.ai/ko/privacy.md): What visit data is collected (anonymous GA4 only), and how to opt out.

## Citation

Cite as: reopt architecture (reopt Inc.), https://architecture.reopt.ai/. Referencing and quoting with attribution is welcome; reproducing the site's visual design or layout for another product is not.