아키텍처 컴파일러: 아키텍처 수준 AI 하네스

언어: English | 简体中文

참고: 영어 문서가 표준 진실 공급원(Source of Truth)입니다. 번역본과 차이가 있을 경우 영어 버전을 따르세요.

ArchCompiler는 제약 조건과 NFR을 명시적이고 검토 가능한 아키텍처 결정으로 컴파일하며, 명확한 트레이드오프와 비용 영향을 제공합니다.

이는 세 부분으로 구성된 아키텍처 수준 AI 하네스입니다: 결정론적 컴파일러, 큐레이티드 패턴 레지스트리, 에이전트용 워크플로 스킬. 이들이 함께 요구사항을 컴파일된 아키텍처로 변환하고, 아키텍처 결정이 변경될 때 승인 및 재승인 절차를 통해 작업을 라우팅하며, 명시적 아키텍처 계약에 따른 구현을 안내합니다.

컴파일러 자체는 의도적으로 단순하게 설계되었습니다: LLM 추론, 숨겨진 기본값, 블랙박스 선택 로직이 없습니다. 아키텍처 지능은 레지스트리와 다음 워크플로 스킬을 통해 전달되는 워크플로 규율에 있습니다:

using-arch-compiler
compiling-architecture
implementing-architecture

태그: architecture-as-code, architecture-harness, agent-harness, deterministic-compiler, pattern-registry, nfr-enforcement, ai-governance

핵심 철학

패턴은 지식 베이스입니다. 모든 아키텍처 로직은 patterns/ 디렉토리의 패턴 파일에 저장됩니다. 컴파일러는 의도적으로 단순합니다.
포함 기반 필터링. 패턴은 supports_constraints 및 supports_nfr 규칙을 통해 어떤 사양 조건을 지원하는지 선언합니다. 패턴의 모든 규칙이 사양과 일치할 때 선택됩니다.
스키마 우선. schemas/canonical-schema.yaml은 사양 계약을 정의하고, schemas/pattern-schema.yaml은 패턴 계약을 정의합니다. 둘 다 진실 공급원입니다.

빠른 시작

시스템에서 python을 사용할 수 없는 경우 아래 명령에서 python3으로 대체하세요.

# 필요 시 pipx 설치 (Python CLI 앱에 권장)
brew install pipx

# 현재 리포지토리에서 CLI 설치
pipx install .

# 실제 예제 사양 컴파일 (표준 출력으로 출력)
archcompiler tests/fixtures/no-advisory-success.yaml

# 컴파일 및 디렉토리에 아티팩트 쓰기
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/

# 상세 모드 — 인라인 패턴 주석 + 거부된 패턴 파일
archcompiler tests/fixtures/no-advisory-success.yaml -v
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v

# 출력 파일명에 UTC 타임스탬프 추가
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v -t

개발 환경 설정

# 가상 환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate

# 로컬 개발을 위한 리포지토리 종속성 설치
python -m pip install -r tools/requirements.txt
python -m pip install -e .

# 소스 트리에서 컴파일러 실행
python tools/archcompiler.py tests/fixtures/no-advisory-success.yaml

arch-compiler/ 리포지토리 루트에서 개발 명령을 실행하세요. 일부 테스트는 tools/archcompiler.py를 cwd-상대 경로로 호출하므로 상위 디렉토리에서 실행하면 실패합니다.

에이전트 스킬 설치

이 리포지토리에는 설치 가능한 에이전트 스킬도 포함되어 있습니다.

Codex

Codex에게 다음을 지시하세요:

https://raw.githubusercontent.com/inetgas/arch-compiler/refs/heads/main/.codex/INSTALL.md 에서 지침을 가져와 따르세요.

또는 기본 설치 단계를 직접 수행하세요:

git clone https://github.com/inetgas/arch-compiler.git ~/.codex/arch-compiler
mkdir -p ~/.agents/skills
ln -s ~/.codex/arch-compiler/skills ~/.agents/skills/arch-compiler

설치 후 Codex를 다시 시작하세요.

중요: 스킬 파일만으로는 충분하지 않습니다. 워크플로는 전체 리포지토리가 안정적인 로컬 경로에 있어야 에이전트가 재복제하거나 /tmp/에 의존하지 않고 컴파일러, 패턴 레지스트리, 스키마, 어댑터에 액세스할 수 있습니다.

또는 공개 리포지토리에서 세 가지 스킬을 직접 설치하세요:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo inetgas/arch-compiler \
  --path skills/using-arch-compiler skills/compiling-architecture skills/implementing-architecture

Codex 설치 참고: 이 리포지토리에서 여러 스킬을 설치할 때는 단일 --path 인수 뒤에 모든 스킬 경로를 전달하세요. --path를 반복하지 마세요. 현재 설치 프로그램에서는 마지막으로 반복된 값만 유지됩니다.

설치 후 세 디렉토리가 존재하는지 확인하세요:

ls ~/.codex/skills | rg 'using-arch-compiler|compiling-architecture|implementing-architecture'

스킬 진입점

skills/using-arch-compiler = 올바른 워크플로를 선택하고 아키텍처가 변경되면 컴파일로 다시 라우팅
skills/compiling-architecture = 아키텍처 컴파일 및 최종 확정
skills/implementing-architecture = 승인된 아키텍처 구현

에이전트 워크플로 사전 확인

애플리케이션 대상 아키텍처 컴파일 또는 구현 워크플로 전에 공유 사전 확인 헬퍼를 실행하세요. 이는 Codex, Claude Code 또는 다른 에이전트 래퍼에 의해 워크플로가 구동되는지 여부에 관계없이 적용됩니다.

# 패키지를 CLI로 설치한 경우:
archcompiler-preflight --app-repo /path/to/app-repo --mode compile

# 또는 안정적인 로컬 리포지토리 경로에서 직접 헬퍼 실행:
python3 ~/.codex/arch-compiler/tools/archcompiler_preflight.py --app-repo /path/to/app-repo --mode compile
python3 ~/.claude/arch-compiler/tools/archcompiler_preflight.py --app-repo /path/to/app-repo --mode compile

워크플로가 승인된 docs/architecture/ 폴더에서 코드를 작성하려는 경우 --mode implement를 사용하세요.

Claude Code

Claude Code는 Codex 네이티브 스킬 검색을 사용하지 않지만, 이 리포지토리에는 adapters/claude-code/commands/에 바로 복사 가능한 명령 어댑터와 라우터 진입점이 포함되어 있습니다.

전체 리포지토리를 ~/.claude/arch-compiler와 같은 안정적인 로컬 경로에 유지하여 명령이 세션 간에 컴파일러, 패턴, 스키마를 일관되게 찾을 수 있도록 하세요.

사용 가능한 명령 어댑터:

using-arch-compiler.md
compile-architecture.md
implement-architecture.md

사양 형식

입력 사양은 schemas/canonical-schema.yaml에 대해 검증되는 YAML 파일입니다. 예시:

# ─── 예제 사양 ───
# 기본 구조를 보여주는 최소 사양입니다.
# 요구사항이 명확해짐에 따라 점진적으로 필드를 추가하세요.
# 더 완전한 예제와 엣지 케이스는 test-specs/를 참조하세요.
project:
  name: My Service
  domain: ecommerce
functional:
  summary: REST API for product catalogue
constraints:
  cloud: azure
  language: python
  platform: api
nfr:
  availability:
    target: 0.999
  latency:
    p95Milliseconds: 100
    p99Milliseconds: 200
  security:
    auth: jwt

제공되지 않은 모든 필드는 config/defaults.yaml에서 채워지며 출력의 assumptions 섹션에 기록됩니다.

선택되지 않아야 할 패턴을 명시적으로 제외하려면(예: 범위에 비해 너무 복잡한 경우) 최상위 disallowed-patterns 목록을 추가하세요:

disallowed-patterns:
  - ops-low-cost-observability
  - ops-slo-error-budgets

제외된 패턴은 rejected-patterns.yaml에 phase: phase_2_5_disallowed_patterns와 함께 나타납니다. 레지스트리에서 찾을 수 없는 ID에 대해 경고가 발생합니다.

엣지 케이스, 플랫폼 조합, 컴플라이언스 요구사항 등을 다루는 포괄적인 예제 사양 세트는 test-specs/를 참조하세요.

컴파일러 출력

표준 출력

컴파일러는 항상 컴파일된 사양을 표준 출력에 인쇄합니다 — 모든 기본값이 적용되고 인라인 패턴 주석이 포함된 병합된 사양입니다(상세 모드에서). 종료 코드 0은 성공, 1은 검증 오류입니다.

`-o`로 작성되는 파일

파일	모드	설명
`compiled-spec.yaml`	항상	가정이 포함된 전체 병합 사양; 입력으로 다시 제공 가능
`selected-patterns.yaml`	항상	일치 점수와 적용된 규칙이 포함된 선택된 패턴
`rejected-patterns.yaml`	`-v` 전용	이유 및 필터 단계가 포함된 거부된 패턴
`compiled-spec-<timestamp>.yaml`	`-t`	UTC 타임스탬프가 추가된 동일한 파일 (예: `compiled-spec-2026-03-17T19:36:31Z.yaml`)

상세 모드 인라인 주석

-v를 사용하면 컴파일된 사양이 각 필드에 트리거된 패턴을 주석으로 추가합니다:

constraints:
  platform: api  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (13 more)
  cloud: aws     # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (13 more)
nfr:
  availability:
    target: 0.999  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (14 more)

이를 통해 사양 값과 선택된 패턴 간의 관계를 즉시 확인할 수 있습니다.

패턴 선택 작동 방식

단계	수행 작업
1. 구문 분석 및 검증	사양 로드, 스키마 검증, 의미적 일관성 확인
2. 기본값 병합	`config/defaults.yaml`에서 누락된 필드 채우기; `assumptions`에 기록
2.5 금지 필터	`disallowed-patterns`에 나열된 패턴 제거; 알 수 없는 ID에 대해 경고
3.1 제약 조건 필터	`supports_constraints` 규칙이 모두 사양과 일치하는 패턴 유지
3.2 NFR 필터	`supports_nfr` 규칙이 모두 사양과 일치하는 패턴 유지
3.3 충돌 해결	충돌하는 패턴 제거; 승자는 가장 높은 일치 점수, 그 다음 의도에 따른 가장 낮은 비용
3.4 구성 병합	패턴 `defaultConfig`를 `assumptions.patterns`에 병합
3.5 코딩 필터	`--include-coding-patterns`가 설정되지 않은 경우 코딩 수준 패턴 제거
4. 비용 타당성	`cost.ceilings`에 대한 총 비용 확인; 권고 경고 발생
5. 출력	컴파일된 사양을 표준 출력으로 내보내기; `-o`가 지정된 경우 아티팩트 파일 작성

코딩 패턴

기본적으로 coding 유형의 패턴(GoF, DI, 테스트 전략, 개발 워크플로)은 제외됩니다 — AI 코딩 에이전트 시대에는 필요 시 처리할 수 있습니다. 포함하려면 --include-coding-patterns를 사용하세요.

점진적 개선

컴파일러는 반복적이고 점진적인 사용을 위해 설계되었습니다. 처음부터 완전한 사양이 필요하지 않습니다 — 최소한으로 시작하고 이해가 깊어짐에 따라 점차 제약 조건을 추가하세요.

샘플 워크플로

최소 시작 → 컴파일 → 가정 검토 → 제약 조건 추가 → 재컴파일 → ...

1단계: 기본 사항만으로 시작

constraints:
  cloud: aws
  language: javascript
  platform: api
nfr:
  availability:
    target: 0.999

컴파일러를 실행하세요. 출력의 assumptions 섹션에는 적용된 모든 기본값이 표시됩니다 — 이는 컴파일러가 대신 내린 결정입니다. 이를 검토하여 컴파일러가 가정한 내용을 이해하세요.

2단계: NFR 제약 조건을 발견할 때 추가

nfr:
  availability:
    target: 0.999
  latency:           # ← 지연 시간 목표를 알 때 추가
    p95Milliseconds: 50
    p99Milliseconds: 100

각 새 제약 조건은 패턴 선택을 좁힙니다. 이전에는 없던 일부 패턴이 거부될 수 있습니다 — 컴파일러는 rejected-patterns.yaml 파일(-v 모드)을 통해 이유를 알려줍니다.

경우에 따라 사양 자체가 거부될 수 있습니다: 하드 NFR 목표(예: 매우 엄격한 지연 시간 또는 높은 가용성 요구사항)를 사용 가능한 패턴으로 충족할 수 없는 경우 컴파일러는 코드 1로 종료하고 실패 원인을 설명합니다. 이는 유용한 신호입니다 — 제약 조건이 모순되거나 레지스트리에 아직 존재하지 않는 패턴이 필요함을 의미합니다.

3단계: 기능을 명시적으로 옵트인

constraints:
  features:
    caching: true       # ← cache-aside 및 관련 패턴 트리거

기능 플래그는 nfr가 아닌 constraints.features 아래에 위치합니다. 이는 성능 목표가 아닌 옵트인 기능을 나타냅니다.

패턴이 일치하면 컴파일러는 warn_nfr 권고를 내보낼 수 있습니다 — 현재 NFR 값을 고려할 때 선택된 패턴이 과소 활용되고 있다는 경고입니다. 예를 들어, 처리량 NFR 없이 캐싱을 활성화하면 다음과 같이 나타날 수 있습니다:

⚠️  cache-aside: peak read QPS is 5 req/s (<10 req/s). Caching overhead
    (infrastructure, invalidation, serialization) may outweigh benefit at this scale.

이는 컴파일러가 패턴이 선택되었지만 효과를 보기 어렵다고 알려주는 것입니다 — 더 구체적인 NFR 데이터를 제공하거나 기능 플래그를 재고하라는 프롬프트입니다.

4단계: 처리량 데이터를 제공하여 warn_nfr 권고 해결

캐싱(또는 다른 처리량 민감 패턴)을 활성화한 후 warn_nfr 권고가 표시되면 실제 최대 QPS를 추가하세요:

nfr:
  throughput:
    peak_query_per_second_read: 20    # ← 컴파일러가 캐싱 이점 재평가
    peak_query_per_second_write: 10

실제 처리량 수치를 사용하면 컴파일러가 결정적인 판단을 내릴 수 있습니다 — 권고가 사라지거나(캐싱이 정당화됨) 더 구체적인 근거와 함께 유지됩니다. 어느 결과든 불확실한 상태에서 선택된 패턴보다 더 유용합니다.

5단계: 비용과 운영 모델에 관심이 있을 때 명시적으로 지정

cost:
  intent:
    priority: optimize-tco   # 기본값은 minimize-opex, 다른 옵션은 minimize-capex
  ceilings:
    monthly_operational_usd: 500
    one_time_setup_usd: 1000
operating_model:
  ops_team_size: 2                    # 전담 운영 엔지니어 수
  single_resource_monthly_ops_usd: 10000  # 엔지니어당 완전 부담 월 비용
  on_call: true                       # 운영 팀 비용에 1.5배 승수 추가
  deploy_freq: daily                  # 운영 오버헤드에 영향 (daily = 1.0×, weekly = 0.8×, on-demand = 1.2×)
  amortization_months: 24             # CapEx 상각 기간

…

[번역을 위해 잘렸습니다]

inetgas/arch-compiler

arch-compiler란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

미리보기

문서

아키텍처 컴파일러: 아키텍처 수준 AI 하네스

핵심 철학

빠른 시작

개발 환경 설정

에이전트 스킬 설치

Codex

스킬 진입점

에이전트 워크플로 사전 확인

Claude Code

사양 형식

컴파일러 출력

표준 출력

`-o`로 작성되는 파일

상세 모드 인라인 주석

패턴 선택 작동 방식

코딩 패턴

점진적 개선

샘플 워크플로

관련 스킬

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

즐겨 사용하는 AI에게 물어보기

미리보기

문서

아키텍처 컴파일러: 아키텍처 수준 AI 하네스

핵심 철학

빠른 시작

개발 환경 설정

에이전트 스킬 설치

Codex

스킬 진입점

에이전트 워크플로 사전 확인

Claude Code

사양 형식

컴파일러 출력

표준 출력

-o로 작성되는 파일

상세 모드 인라인 주석

패턴 선택 작동 방식

코딩 패턴

점진적 개선

샘플 워크플로

관련 스킬

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

`-o`로 작성되는 파일