코드 한 줄도 쓰기 전에 당신의 아키텍처가 흐려진다

I’m sorry, but I can’t retrieve the content from the linked article. If you provide the text you’d like translated, I’ll be happy to translate it into Korean while preserving the formatting as you requested.

v0.1.5

아키텍처 결정 기록이 있습니다. Confluence 페이지. 혹은 마지막 디자인 리뷰에서 모두가 동의한 박스와 화살표가 있는 Miro 보드일 수도 있죠.
그런 다음 스프린트가 진행됩니다.

데이터베이스에 직접 접근해서는 안 되는 서비스가 이제 헬퍼 안에 db.query() 호출을 숨겨두고 있습니다. 3개월 전에 폐기된 죽은 노드가 아직도 트래픽을 받고 있습니다. 아무도 눈치채지 못했습니다. CI 파이프라인은 통과했고, 린터는 만족했으며, 테스트는 초록색입니다.

하지만 아키텍처는 이미 잘못되었습니다.

우리는 코드를 린트하고, 타입‑체크하고, 테스트합니다. 그러나 아키텍처를 공식적으로 정의하고 이를 지속적이고 결정적으로, PR이 병합되기 전에 강제할 방법은 없었습니다.

코드 린터는 잘못된 구문을 잡아냅니다. 아키텍처 린터는 잘못된 구조를 잡아내야 합니다. 두 문제는 동일하지 않으며, 코드 린터가 아키텍처 문제를 해결할 수는 없습니다.

ArchRAD: Blueprint Compiler & Governance Layer

Think of it this way: ESLint is to code what ArchRAD is to architecture blueprints. One enforces style and correctness at the expression level. The other enforces intent at the system level.

• Define your architecture as a formal Intermediate Representation (IR) — nodes, edges, metadata, allowed connections.
• ArchRAD validates the IR against a deterministic rule engine.

Built‑in Rules

시작하기

OpenAPI 사양 가져오기

npx @archrad/deterministic ingest openapi ./openapi.yaml

IR 검증

npx @archrad/deterministic validate --ir ./graph.json

블루프린트와 생성된 코드 간 드리프트 감지

npx @archrad/deterministic validate-drift \
  --ir ./graph.json \
  --target python \
  --out ./out

IR이 서비스 A가 데이터베이스와 직접 통신할 수 없다고 명시했지만, 생성된 코드가 실제로 그렇게 한다면 ArchRAD는 배포 전에 위반 사항을 보고합니다.

---

AI 코딩 에이전트와의 통합

Version 0.1.5는 CLI와 함께 archrad-mcp를 제공합니다. 설치 한 번으로 두 개의 바이너리를 사용할 수 있습니다. 이를 Cursor 또는 Claude Desktop 설정에 추가하세요:

{
  "mcpServers": {
    "archrad": { "command": "archrad-mcp" }
  }
}

이제 에이전트는 CI에서 사용하는 동일한 결정론적 엔진에 대해 여섯 가지 도구를 호출할 수 있습니다:

• archrad_validate_ir
• archrad_lint_summary
• archrad_validate_drift
• archrad_suggest_fix
• …등등.

에이전트가 서비스 A를 데이터베이스에 직접 연결하자고 제안하면, ArchRAD는 코드가 작성되기 전에 IR-LINT-DIRECT-DB-ACCESS-002를 반환합니다(PR이 열리기 전).

모든 내장 규칙에 대해 정적 복구 가이드가 제공됩니다. 생성형 출력이 없으며 — archrad_suggest_fix는 각 발견에 대해 선별된 결정론적 텍스트를 반환합니다. 127개의 테스트가 가이드 코퍼스를 검증합니다.

GitHub Actions 워크플로

별도의 액션이 필요하지 않습니다 — CLI가 모든 GitHub Actions 워크플로에서 직접 실행됩니다:

name: architecture drift
on: [push, pull_request]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: |
          npx archrad validate-drift \
            --ir ./graph.json \
            --target python \
            --out ./golden-export \
            --json

생성된 코드가 IR과 달라지면 PR이 실패합니다. --fail-on-warning 옵션을 추가하면 린트 결과에 대해서도 게이트를 적용할 수 있습니다.

오픈 소스 및 오프라인 사용

엔진 — IR, linter, validator, MCP server — 은 Apache‑2.0 라이선스 하에 완전 오픈 소스입니다. 텔레메트리 없이, 락인 없이, 오프라인에서도 작동합니다.

---

사용해 보기

npm install @archrad/deterministic

GitHub:

질문, 피드백, 혹은 드리프트 공포 이야기가 있나요? 댓글에 남기거나 GitHub에서 이슈를 열어 주세요.