Archyl Harness

코딩 에이전트는 여러분의 저장소는 완벽하게 알지만, 아키텍처는 전혀 모릅니다. 다른 에이전트가 바로 그 순간 리팩터링 중인 서비스를 다시 작성하고, 2년 전 팀이 ADR로 금지한 의존성을 들여오며, 더 이상 존재하지 않는 시스템을 설명하는 문서를 그대로 남겨 둡니다.

Archyl Harness는 이 문제를 해결합니다. Claude Code, Codex, Cursor, CI 봇, Archyl의 관리형 에이전트 등 어떤 코딩 에이전트든 문서화된 아키텍처 위에 구축된 통제된 루프로 감쌉니다.

구성 요소 역할 도구
Context 작업에 관련된 아키텍처 조각만 에이전트에게 제공합니다 — 요소, 결정, Guardrails, 담당자 find_relevant_context
Plan 기능 요청을 C4 모델과 ADR을 존중하는 구현 계획으로 바꿉니다 plan_work
Guard 적합성 규칙을 위반하는 변경을 작성되기 전에 차단합니다 Guard 훅 + run_conformance_check
Evolve 루프를 닫습니다. 작업 결과는 요소의 메모리가 되고, 아키텍처 변경 요청 초안이 모델을 계속 동기화합니다 finish_work_session

에이전트가 실행하는 루프:

plan_work ──▶ start_work_session ──▶ code (Guard watches every write)
                                          │
finish_work_session ◀─── heartbeat ◀──────┘
      │
      ├─▶ leases released
      ├─▶ outcome pinned to the touched elements (memory)
      └─▶ draft Architecture Change Request (optional)

그리고 모든 세션은 자신이 건드리는 C4 요소에 어드바이저리 리스를 확보하므로, 같은 서비스에서 작업하는 두 에이전트는 충돌하기 전에 서로를 인지합니다 — 각자의 브리핑 안에서, 그리고 다이어그램 위에서 실시간으로.

설계상 선택 사항

하네스는 선택해서 켜는 기능입니다. 아키텍처를 문서화했다는 이유만으로 켜지는 것은 없습니다. 에이전트가 이 루프에 들어오는 것은 다음 세 가지 중 하나를 했을 때뿐입니다. MCP 서버를 ?profile=coding으로 연결하거나, 프로토콜을 가르치는 archyl-harness 스킬을 설치하거나, Guard 훅을 추가하는 것입니다. 이를 되돌리면 해당 저장소의 에이전트는 이전과 똑같이 동작합니다.

Archyl의 나머지 기능은 하네스 없이도 작동합니다. 컨텍스트 조회, 영향 분석, 소유권, 규범 검사, 드리프트 감지, 메모리 시스템은 모두 전체 도구 카탈로그에서 사용할 수 있으며 작업 세션이 전혀 필요하지 않습니다. 에이전트가 읽을 수 있는 문서화된 아키텍처로 Archyl을 쓰면서 이 가이드를 통째로 건너뛰는 것도 충분히 지원되는 사용 방식입니다.

두 축을 따로 도입하는 이유는 허용된 권한이 다르기 때문입니다. 기록은 사람의 큐레이션에서 권위를 얻습니다. ADR도, 규범 규칙도, 승인된 변경 요청도 사람이 넣었기에 상태를 갖고, 잘못된 항목은 누군가 읽고 고칠 때까지 조용히 놓여 있을 뿐입니다. 반면 프로토콜은 에이전트가 실제로 따르는 지시를 내보냅니다. 이는 성격이 다른 위험이며, 기본값이 아니라 의식적인 결정을 거칠 만한 일입니다.

이 경계는 제품 바깥뿐 아니라 제품 안에도 그어져 있습니다. 에이전트는 기록을 읽을 수도, 기록에 쓸 수도 있지만, 쓴 내용은 날짜와 작성자가 붙은 맥락으로 다음 에이전트에게 돌아갈 뿐 결코 규칙이 되지 않습니다. 구속력 있게 제시되는 것은 ADR과 규범 규칙뿐이며, 에이전트가 기록한 무언가가 그 지위에 이르는 길은 사람을 거칩니다. ADR로 만들거나, 누군가 승인한 아키텍처 변경 요청을 통과하는 것입니다.

5분 설정

아키텍처가 문서화된 Archyl 프로젝트(비어 있다면 먼저 AI 기반 탐색을 실행하세요)와 write 범위를 가진 API 키(프로필 → API 키에서 생성)가 필요합니다.

옵션 A — 명령 하나로

저장소 루트에서 실행합니다:

curl -fsSL https://raw.githubusercontent.com/archyl-com/agent-skills/main/templates/setup.sh | bash

스크립트가 API 키와 프로젝트를 묻고, 아래의 모든 설정을 대신 수행합니다. 이것으로 끝입니다 — 첫 번째 세션으로 바로 넘어가세요.

옵션 B — 단계별로

1. coding 프로필로 MCP 서버를 연결합니다. 저장소에 .mcp.json을 생성하거나 기존 파일에 추가합니다:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp?profile=coding",
      "headers": { "X-API-Key": "${ARCHYL_API_KEY}" }
    }
  }
}

?profile=coding이 중요합니다. 도구 표면을 189개에서 코딩 에이전트에게 필요한 16개로 좁혀, 에이전트의 컨텍스트를 작게 유지하고 선택지를 명확하게 만듭니다.

2. 플러그인을 설치합니다(Claude Code):

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-developer@archyl-marketplace

이 명령으로 스킬(세션 프로토콜을 에이전트에게 가르치는 archyl-harness 포함)과 Guard 훅이 설치됩니다.

3. Guard를 활성화합니다. 에이전트가 실행되는 환경에서 두 개의 변수를 내보냅니다:

export ARCHYL_API_KEY=arch_...
export ARCHYL_PROJECT_ID=<your project uuid>

Guard에 필요한 것은 이게 전부입니다. Guard는 fail-open 방식입니다. 이 변수들이 없거나 네트워크가 없으면 아무 일도 하지 않으므로, 여러분의 워크플로우를 망가뜨릴 일이 없습니다.

첫 번째 세션

에이전트에게 아무 변경이나 요청해 보세요 — 예를 들어 "공개 API에 요청 제한을 추가해 줘". 하네스가 설치되어 있으면 다음과 같은 일이 일어납니다.

코딩하기 전에 에이전트가 작업을 선언합니다:

▶ start_work_session(task: "add rate limiting to the public API",
                     agentName: "claude-code/vincent")

# Harness Session
- Session ID: 4c2e…
- Gate: warn
  - error-level guardrail applies: no-direct-db-from-handlers
- Leased elements: container `ApiGateway`, component `RateLimiter`
- Conflicts: none

## Most relevant elements
- ApiGateway (container) — handles all public traffic …
## Related decisions (respect these)
- ADR-017: All throttling is enforced at the gateway [accepted]
## What previous sessions did here
- ApiGateway (claude-code/sarah, 3 days ago): extracted auth middleware …

이제 에이전트는 저장소 전체를 읽지 않고도 어디서 작업해야 하는지, 어떤 결정이 자신을 제약하는지, 직전 에이전트가 그곳에서 무엇을 했는지를 알게 됩니다.

코딩하는 동안 Guard는 에이전트가 작성하려는 모든 파일을 적합성 규칙과 대조합니다. critical 위반은 규칙과 그 제안을 함께 보여 주며 쓰기를 차단하고, 에이전트는 이를 반영해 작업을 이어 갑니다.

작업이 끝나면 에이전트가 루프를 닫습니다:

▶ finish_work_session(sessionId: "4c2e…",
    summary: "Added token-bucket rate limiting in ApiGateway middleware",
    decisions: ["limits configured per-plan in Redis"],
    createChangeRequest: true)

리스가 해제되고, 요약은 다음 에이전트를 위해 ApiGateway의 메모리로 고정되며, 아키텍처 변경 요청 초안이 Archyl에 도착해 C4 모델을 어떻게 갱신할지 사람이 검토할 수 있게 됩니다.

각 결정은 그 자체로 하나의 메모리로 기록됩니다. 이후 세션은 해당 세션이 남긴 다른 내용을 건드리지 않고 그 결정을 대체하거나, 다시 확인하거나, 그대로 낡아가게 둘 수 있습니다. 결정은 이후 에이전트에게 작성자와 날짜가 붙은 맥락으로 돌아올 뿐, 결코 규칙으로 전달되지 않습니다. 에이전트에게 구속력 있게 제시되는 것은 ADR과 규범 규칙뿐이며, 결정이 그 지위를 얻는 경로가 바로 변경 요청입니다.

에이전트 지켜보기: Fleet 콘솔

Agent Hub → Fleet을 열면 진행 중인 작업이 보입니다. 몇 개의 에이전트가 일하고 있는지, 어떤 C4 요소가 현재 점유되어 있는지, 그리고 활성 세션마다 작업·점유 요소·게이트·하트비트 신선도를 담은 카드가 표시됩니다. 끝난 세션은 각자 보고한 요약과 함께 최근 세션으로 내려갑니다.

Fleet 콘솔 — 모든 에이전트 세션과 각자가 점유한 요소

하트비트가 멈춘 세션은 표시되며 30분 뒤 스스로 만료됩니다. 여기서 취소하면 점유가 즉시 해제됩니다.

같은 정보가 실제로 보게 되는 곳 — 다이어그램 위 — 에도 도달합니다. 에이전트가 점유한 요소에는 그 이름의 배지가 붙고, 클릭하면 무엇을 하고 있는지 묻는 셈이 됩니다. 선언된 작업, 그 밖에 점유 중인 요소, 마지막으로 신호를 보낸 시점이 돌아옵니다.

캔버스에서 작업 중인 에이전트 — 배지가 이름을, 말풍선이 작업 내용을 알려줍니다

Archyl의 관리형 에이전트라면 실행 중인 에이전트를 조종할 수도 있습니다. 실행 페이지에 메시지를 쓰면 다음 추론 단계에 주입됩니다.

게이트

모든 세션은 프리플라이트 판정으로 시작합니다:

Gate 의미 에이전트 동작
allow 충돌 없음, error 수준 Guardrails 없음 진행
warn 다른 세션이 대상 요소의 리스를 보유 중이거나, error 수준 Guardrail이 적용됨 진행하되 나열된 모든 사유를 처리
deny exclusive: true인 경우에만 — 대상 요소에서 이미 작업이 진행 중 우회하지 말고 사용자에게 보고

스키마 마이그레이션이나 계약 변경처럼 누구와도 경합해서는 안 되는 변경에는 exclusive: true를 사용하세요.

Guard 설정

변수 기본값 용도
ARCHYL_API_KEY — Guard 활성화에 필수
ARCHYL_PROJECT_ID — Guard 활성화에 필수
ARCHYL_API_URL https://api.archyl.com 셀프 호스팅 배포용
ARCHYL_GUARD_BLOCK critical critical은 critical 위반을 차단하고, high는 high도 차단하며, off는 차단을 비활성화

환경 변수 대신, 저장소 루트에 커밋 가능한 .archyl.json을 두어 비밀이 아닌 절반을 담을 수 있습니다: { "apiUrl": "…", "projectId": "…" }. API 키는 환경 변수에 두세요.

메모리

세션 작업 결과는 메모리의 자동으로 쌓이는 절반일 뿐입니다. 에이전트와 팀원은 의도적으로 메모리를 기록할 수도 있습니다:

▶ remember(projectId: …, element: "ApiGateway", kind: "pitfall",
    content: "The gateway strips custom headers longer than 8KB — payloads must go in the body.")
  • remember는 사실 하나를 요소(또는 프로젝트 전체)에 note, convention, pitfall 중 한 가지 유형으로 고정합니다. 코드에도 모델에도 드러나지 않는 지식, 즉 배포상의 특이점, 역사적인 이유, 취약한 지점에 사용하세요.
  • recall은 작업 결과, 노트, 컨벤션, 함정을 아우르는 메모리 전체를 검색어, 요소, 유형으로 찾습니다. 순위는 단어뿐 아니라 의미까지 함께 반영하므로, "rate limiting"을 묻는 에이전트가 다른 누군가 "throttling"에 대해 써 둔 노트를 찾아냅니다. 자신의 sessionId를 함께 넘기면, 제공받은 메모리의 기여를 나중에 인정할 수 있습니다.
  • find_relevant_context와 start_work_session은 해당 요소의 최신 메모리를 자동으로 함께 제공하므로, 다음 에이전트는 앞선 에이전트들이 배운 것에서 출발합니다.

메모리 기록은 중복 제거됩니다. 이미 있는 사실을 다시 적어도 사본이 하나 더 저장되지 않고, 기존 메모리를 확인합니다(응답에 deduplicated: true가 담깁니다). 에이전트가 배운 것을 다시 확인해 주는 일은 잡음이 아니라 근거이기 때문입니다. 비슷하지만 똑같지는 않은 메모리는 그대로 저장되고 similarTo로 함께 알려 주므로, 작성자는 조용히 모순을 만드는 대신 의도적으로 기존 메모리를 대체하게 됩니다.

메모리는 사용에서도 배웁니다. 세션이 끝날 때 usedMemories는 그 세션이 실제로 의지한 메모리를 지목합니다. 이 인용이 바로 강한 신호입니다. 인용된 메모리는 순위를 유지하고, 다섯 개 세션에 제공되었는데도 어느 세션에서도 지목되지 않은 메모리는 잡음으로 순위가 내려갑니다. 자동으로 삭제되는 것은 없습니다. 외면받은 메모리는 검토 대기열에 올라가 사람이 판단합니다.

메모리에는 수명 주기가 있어서, 쌓이기만 하는 대신 사실인 상태를 유지합니다. recall이 내어준 메모리가 정확한 것으로 확인되면 confirm_memory로 다시 확인해 주세요. 신선도 시계가 초기화되어 더 오래된 정보보다 계속 앞서게 됩니다. 사실이 바뀌었다면 두 버전을 모두 살려 두지 마세요. remember(supersedes: "Old title")은 기존 메모리를 대체하며, 대체된 메모리는 검색에서 빠지지만 이력과 그래프에는 남습니다. 확인되지 않은 것은 순위에서 완만하게 감쇠하고(반감기 45일), 이제 막 코드를 바꾸려는 에이전트에게 함정은 언제나 단순한 노트보다 앞섭니다.

메모리는 Obsidian처럼 지식 그래프를 이룹니다. 메모리에 title을 붙이면 주소를 가지게 되어, 다른 어떤 메모리든 본문에서 [[Title]]로 참조할 수 있습니다. 링크는 C4 요소를 이름으로([[ApiGateway]]), 결정을 번호로([[ADR-17]]) 해석하기도 합니다. 아직 존재하지 않는 제목으로 건 링크는 보류 상태로 남아 있다가 그 메모리가 만들어지는 순간 연결됩니다. 모든 메모리는 백링크를 함께 보여주므로 지식을 양방향으로 탐색할 수 있습니다. 나아가 recall은 링크를 따라가서, 상위로 일치한 메모리가 위키 링크로 이어진 이웃 메모리까지 via 표시와 함께 데려옵니다.

메모리는 아키텍처가 발밑에서 움직였다는 것도 알아챕니다. 메모리가 고정된 요소가 바뀌면 그 메모리는 검토 대상으로 표시됩니다. recall은 여전히 제공하지만 [VERIFY — the element drifted since this was written]라고 표시하고, 사라지는 대신 순위가 내려갑니다. 이후 분리된 서비스에 대해 쓰인 사실이 자동으로 틀린 것은 아닙니다 — 사람이 확인하기 전까지 신뢰할 수 없게 될 뿐입니다.

메모리는 다른 민감한 콘텐츠 열과 마찬가지로 저장 시 암호화되며, UI에서 관리할 수 있습니다. Agent Hub의 메모리 패널과 다이어그램 상세 패널의 요소별 섹션입니다. 이 패널은 분류를 위해 만들어졌습니다 — 왼쪽 레일이 검토가 필요한 것, 무시되고 있는 것, 오래된 것을 세고 나머지를 종류별로 나누며, 각 행은 얼마나 믿을 수 있는지를 한눈에 보여주는 색상 척추를 답니다.

프로젝트 메모리 — 관례, 함정, 결과를 신뢰도 기준으로 분류

다른 질문에는 지식 지도로 전환하세요. 무엇을 아는가가 아니라 어디를 아는가입니다. C4 요소마다 한 칸씩, 프로젝트가 그것에 대해 무엇을 알고 그 지식이 얼마나 신선한지 보여줍니다 — 아무도 아무것도 쓰지 않은 요소까지 포함해서. 대개 그쪽이 더 유용한 절반입니다.

지식 지도 — 각 요소에 대해 무엇을 알고, 어디를 모르는지

CI에서

동일한 구성 요소가 GitHub Actions를 통해 파이프라인에서도 실행됩니다. generate-context는 MCP에 접근할 수 없는 에이전트를 위해 archyl.txt 브리핑을 커밋하고, conformance-check는 규칙을 기준으로 풀 리퀘스트를 통제하며, auto-cr은 병합된 변경으로부터 아키텍처 변경 요청을 생성합니다.

문제 해결

Fleet 콘솔에 세션이 나타나지 않습니다. 에이전트가 하네스 프로토콜 없이 연결된 상태입니다. 플러그인이 설치되어 있는지(archyl-harness 스킬이 프로토콜을 가르칩니다), 그리고 MCP URL에 ?profile=coding이 포함되어 있는지 확인하세요. 189개 도구 전체 카탈로그에서는 에이전트가 루프를 따르지 않고 탐색에 빠지는 경우가 많습니다.

Guard가 아무것도 차단하지 않습니다. 의도된 동작으로, fail-open 방식입니다. 에이전트가 실행되는 환경에 ARCHYL_API_KEY 와 ARCHYL_PROJECT_ID가 모두 내보내져 있는지, 그리고 프로젝트에 critical 심각도의 적합성 규칙이 있는지 확인하세요.

세션이 활성 상태로 멈춰 있습니다. 세션은 마지막 하트비트로부터 30분이 지나면 만료되며 리스를 자동으로 해제합니다. 즉시 해제하려면 Fleet 콘솔에서 세션을 취소하세요.

어떤 에이전트가 지원되나요? MCP를 사용하는 모든 도구가 Context, Plan, 세션 프로토콜을 이용할 수 있습니다. Guard 훅과 스킬은 현재 Claude Code를 대상으로 하지만, 다른 에이전트도 run_conformance_check나 CI 액션을 통해 동일한 규칙을 적용할 수 있습니다.