Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
ArchHarness는 엔터프라이즈 아키텍처 설계 및 검증을 위한 스킬 팩입니다. 이 도구는 AI 코딩 어시스턴트를 요구사항 분석가, 보안 감사자 등 전문 팀으로 변환하여 활용합니다. Azure, AWS 등 주요 클라우드 환경에서 실제 작동하는 아키텍처 청사진과 표준 검사 예제를 제공하며, D2와 draw.io로 결과를 시각화합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기English | 中文
Claude Code, OpenCode, Codex, GitHub Copilot, 그리고 Cursor를 위한 엔터프라이즈 아키텍처 설계 및 검증 스킬 팩입니다.
ArchHarness는 AI 코딩 어시스턴트를 아키텍처 전문가 팀으로 변환합니다. 이 팀은 요구사항 분석가, 선임 아키텍트, 과도하게 의심하는 보안 감사자, 위원회 검토자, 그리고 기술 작가로 구성되어 있으며, 각 전문가는 단일 명령어로 필요할 때마다 호출할 수 있습니다.
<img src="https://raw.githubusercontent.com/axisvela/ea-harness/HEAD/docs/images/hero-d2.png" alt="Rendered ArchHarness output — Azure Hub-Spoke with on-premises DCs (D2 render)" width="880">D2로 렌더링됨. 하나의 아키텍처 모델은 편집 가능한 소스용 draw.io와 선명한 프레젠테이션 출력을 위한 D2 두 가지 렌더러 모두로 컴파일됩니다.
이 페이지의 이미지는 D2 렌더입니다.
단순히 README만 있는 저장소는 아닙니다.
archharness는 실제 CLI(python -m archharness), 다중 프로젝트 작업 공간 레이아웃, 그리고 단일 설정 파일에서 엔터프라이즈 값을 로드하는 플랫폼 스킬을 제공하며, 그 결과를 증명합니다: 모든 아티팩트는 해시(hash)로 검증되며 게이트는 결정론적(deterministic)입니다.
여섯 가지 작동 예제가 각 플랫폼 표준별로 하나씩 존재하며, 모두 엔드투엔드 방식으로 실행 가능합니다: 요구사항, req/v2 인벤토리, 아키텍처 청사진, 렌더링된 다이어그램, 그리고 표준 검사입니다. 타일은 D2 렌더를 보여주며, 클릭하면 해당 예제가 열리고 여기에는 편집 가능한 draw.io 소스도 포함되어 있습니다.
총 11개의 예시가 있습니다. 01–06은 프라이빗 클라우드, AWS, Azure를 다루며, 09–11에는 Google Cloud, Microsoft SaaS, Alibaba Cloud가 추가되었고, 07–08은 입력 대기 중인 스캐폴드(scaffolds)입니다. 각 예시는 독립적이며 버전 관리가 이루어지므로, 전체 매트릭스와 실행 방법은 examples/README.md를 참조하십시오.
모든 예시는 동일한 모델을 두 가지 형식으로 제공하며, 각 렌더러는 고유의 역할을 수행합니다:
| 렌더러 | 아티팩트(Artifacts) | 이유 (Why) |
|---|---|---|
| draw.io | diagram-v<N>.drawio | 편집 가능한 소스 전용. 레이아웃이나 주석을 수동으로 조정하려면 draw.io 데스크톱 앱에서 열어야 합니다. 기본적으로 이미지를 생성하지 않으므로, --png-engine drawio를 사용하면 draw.io PNG 렌더링으로 다시 설정할 수 있습니다. |
| D2 | diagram-v<N>.d2 + PNG/SVG | 이미지 렌더러 (기본값). 하나의 명령어(d2 --layout elk diagram.d2 out.png)로 더 선명하고 일관성 있게 생성됩니다. 따라서 위의 갤러리와 히어로 섹션은 D2를 사용합니다. d2 CLI가 없는 경우 matplotlib으로 폴백(fallback)합니다. 매우 큰 다이어그램은 d2의 라스터 백엔드(raster backend) 용량을 초과할 수 있으므로, --d2-scale 0.2를 전달하거나 (d2 --scale로 .d2 파일을 직접 렌더링하여) 크기를 조정하십시오. |
두 렌더러 모두를 통해 동일한 모델(예시 09):
draw.io — 편집 가능한 소스
<img src="https://raw.githubusercontent.com/axisvela/ea-harness/HEAD/docs/images/renderers-drawio.png" alt="Example 09 rendered with draw.io" width="560">D2 — 발표용 렌더링
<img src="https://raw.githubusercontent.com/axisvela/ea-harness/HEAD/docs/images/renderers-d2.png" alt="Example 09 rendered with D2" width="880">| 에이전트 / 스킬 | Claude Code | OpenCode | 역할 |
|---|---|---|---|
| arch-workflow | /arch-workflow | @arch-workflow | 파이프라인 게이트키퍼 — 단계 순서를 강제하며, BLOCK은 파이프라인을 중지시킵니다. |
| ... |
Requirements → arch-design → draw in draw.io → arch-validate
│
arch-enforce gate
...
파이프라인은 필수적이며 아티팩트(artifacts)에 의해 게이트가 설정됩니다. 순서와 필요한 입력/출력 파일은 standards/workflow.yaml에 정의되어 있습니다.
arch-workflow 게이트키퍼는 단계가 시작되기 전에 다음 단계의 모든 필수 아티팩트가 존재하는지(그리고 enforce 게이트가 PASS 또는 WARN을 기록했는지) 확인합니다. BLOCK 결정은 발견된 문제들이 수정되고 검증이 재실행될 때까지 파이프라인을 중지시킵니다. 단계를 건너뛰거나 이전 단계의 출력을 조작하지 마십시오. 의심스러울 때는 @arch-workflow status 또는 @arch-workflow can <stage>를 호출하십시오.
기록된 아티팩트는 이름만으로 확인되는 것이 아니라 해시(hash)로 검증됩니다. 더 이상 디스크의 파일과 일치하지 않는 매니페스트는 게이트가 닫히도록 실패하게 하므로, 기록된 결정 아래에서 다이어그램을 편집할 수 없습니다. python -m archharness workflow verify를 실행하면 해당 발견 사항들을 직접 보고하며, 어떤 아티팩트라도 오래되었거나 변경된 경우 1로 종료됩니다.
제품 기능성(product capability), 엔지니어링 품질(engineering quality), 그리고 참조 콘텐츠에 대한 저장소 수준의 우선순위는 docs/ROADMAP.md에서 유지됩니다.
상세한 draw.io 레이아웃 및 연결 라우팅 계획은 DIAGRAM_GENERATION_ANALYSIS.md에 유지됩니다.
릴리스되었거나 릴리스되지 않은 변경 사항, 그리고 소비자가 고정하는 인터페이스(interfaces consumers pin)는 CHANGELOG.md에 나열되어 있습니다. 새로 클론한 상태에서 게이티드 다이어그램까지의 단계별 워크스루와 각 일반적인 실패에 대한 진단은 docs/first-run.md에 있으며, 모든 풀 리퀘스트(pull request)에서 게이트를 실행하는 레시피와 보관된 증거는 docs/ci-pipeline.md에 있습니다. 그리고 AXISRobo-PAMP의 엔진↔플랫폼 경계에는 개인 정보 보호 기능을 유지하는 관측 가능성(observability) 계약인 metrics/v1이 포함되어 있으며, 이는 docs/pamp-integration.md에 있습니다. 현재 (D2) 이미지와 비교하여 측정된 바인딩 상태를 가지고 예시를 재검증하는 방법은 docs/revalidation-guide.md에 나와 있습니다.
git clone https://github.com/axisrobo/ea-harness.git
cd ea-harness
저장소 루트에 있는 **config.yaml**을 편집하여 귀하의 조직 인프라(DC 이름, 플랫폼 이름, 분류 접두사)와 일치시키십시오. 스킬 및 LLM 규칙은 이 값들을 런타임에 로드합니다.
company:
name: "Acme Corp"
...
여러 아키텍처 프로젝트를 관리하는 경우, 이러한 회사 값을
config.yaml에 한 번 넣고 **격리된 프로젝트(isolated projects)**를 생성하십시오(다음 단계). 프로젝트별 입력 및 출력은projects/<id>/아래에 존재합니다.
하나의 작업 공간(workspace)이 많은 아키텍처 프로젝트를 담을 수 있습니다. 각 프로젝트는 자체적인 input/, working/, 그리고 output/ 디렉터리 트리를 가지므로 파일들이 프로젝트 간에 섞이는 것을 방지합니다.
# POSIX / macOS / Linux
python -m archharness init-workspace .
python -m archharness init-project payments --name "Payments Platform" --default
...
# Windows PowerShell
python -m archharness init-workspace .
python -m archharness init-project payments --name "Payments Platform" --default
...
이 명령어들은 다음 구조를 생성합니다:
projects/payments/
├─ project.yaml # id, name, platform, data classification (ID, 이름, 플랫폼, 데이터 분류)
├─ input/ # documents, diagrams, api exports, requirements (문서, 다이어그램, API 내보내기, 요구사항)
...
project.yaml과 생성된 모든 파일은 git에 의해 무시됩니다(git-ignored). 커밋을 선택할 때 추적되는 것은 project.yaml과 README.md뿐입니다.
프로젝트 디렉토리 내에서 작업하면 도구와 스킬이 활성 프로젝트를 자동으로 감지합니다 (--project는 워크스페이스의 어느 위치에서도 작동합니다).
# POSIX / macOS / Linux
./install.sh
...
또는 수동으로:
pip install -e ".[all]"
python -m archharness init-workspace . # 위에서 생성되지 않은 경우에만 실행
python -m archharness doctor # 설치 검증
설치 프로그램은 스킬을 사용자의 AI 도구에 등록하고, 누락된 경우 작업 공간(workspace)을 생성하며, doctor를 실행합니다. 만약 다른 작업 디렉토리에서 도구를 실행해야 한다면 환경 변수에 ARCHHARNESS_HOME=/path/to/ea-harness를 추가하십시오.
Claude Code
claude .
.claude/skills/ 아래의 스킬들은 /arch-* 슬래시 명령어(slash commands)로 등록됩니다.
OpenCode
opencode .
.opencode/agents/ 아래의 에이전트(Agents)들은 @arch-* 에이전트로 등록됩니다.
Codex / GitHub Copilot / Cursor
도구를 이 리포지토리 루트에 지정하십시오. AGENTS.md는 세 도구 모두가 읽습니다. Codex는 .agents/skills/ 아래의 스킬을 발견하고; GitHub Copilot은 .github/agents/ 아래의 @arch-* 사용자 정의 에이전트를 발견하며; Cursor도 .claude/skills/를 읽습니다.
팁: 작업 디렉토리는 리포지토리 루트(또는 프로젝트 디렉토리)여야 스킬, 도구 및
config.yaml을 자동으로 찾을 수 있습니다.
| 도구 | 프로젝트 규칙 | 스킬 / 에이전트 | 호출 방식 |
|---|---|---|---|
| Claude Code | CLAUDE.md | .claude/skills/ | /arch-validate, /arch-design, … |
| ... | |||
.agents/skills/는 .claude/skills/의 생성된 미러(mirror)입니다. 스킬을 편집한 후에는 python scripts/sync_agents_skills.py를 사용하여 업데이트해야 합니다. CI 환경에서는 미러가 동기화 상태를 유지하도록 강제합니다 (scripts/check_repo.py가 전체 패키지를 검증). |
Claude Code — 네, 플러그인 마켓플레이스(plugin marketplace)를 통해 가능합니다. Claude Code 채팅 창에서는 다음 명령어를 사용합니다:
/plugin marketplace add axisrobo/ea-harness
/plugin install archharness@archharness-marketplace
/reload-plugins
플러그인 스킬은 /archharness:arch-validate, /archharness:arch-design, /archharness:arch-workflow 등과 같이 네임스페이스(namespaced)로 지정됩니다 (플러그인이 스킬의 사본을 캐시합니다). 공유 리소스(standards/, tools/, config.yaml)의 경우, 설치된 패키지 또는 체크아웃(checkout)을 통해 스킬이 해결되므로, 한 번만 pip install archharness[all]를 실행하거나 환경 변수 ARCHHARNESS_HOME을 설정해야 합니다.
다른 모든 도구: 이 저장소를 작업 디렉터리(claude ., opencode ., codex 등으로 열거나 Copilot/Cursor가 이 위치를 가리키도록 지정)로 여십시오. 스킬, 에이전트 및 AGENTS.md는 자동으로 발견되며 tools/, standards/, config.yaml에 접근할 수 있습니다.
설치기(Installers) (install.ps1 / install.sh)는 새로운 클론을 준비합니다: 이들은 Python 패키지를 설치하고, 작업 공간을 초기화하며, doctor를 실행합니다.
| 명령어 | 용도 |
|---|---|
python -m archharness --version | 설치된 버전을 표시합니다. |
| ... |
arch-check, diagram, req, 그리고 validate-yaml은 플래그(flags)를 tools/ 아래의 동일한 Python 도구로 전달하므로, 두 호출 방식 모두 동등하게 작동합니다:
python tools/arch-diagram-gen/arch_diagram_gen.py -i arch.yaml
python -m archharness diagram -i arch.yaml
projects/<id>/ 내부에서 도구를 실행하면 해당 프로젝트가 자동으로 대상이 됩니다. 어디서든 --project <id>를 전달하여 대상을 지정할 수 있습니다.