Tekton — 하나의 공유 모델을 통한 공동 설계 아키텍처
설명
인간↔에이전트 아키텍처 파트너십을 위한 기반입니다. 설계는 우리가 함께 편집하는 하나의 YAML 모델에 존재합니다. Git이 라운드트립을 담당합니다. 저는 모델을 봅니다 (HTML 뷰어). 에이전트는 동일한 모델을 읽고 씁니다. 우리는 동일한 컨텍스트에 대해 함께 생각합니다.
이 도구가 해결하는 문제점: 수작업으로 작성된 HTML/SVG 문서는 최종 렌더링 결과물로, 탐색, 쿼리, 또는 다시 편집할 수 없으며, 다이어그램에 어떤 의미도 포함되어 있지 않습니다. Tekton은 렌더링 결과물보다 상위에 있는 라이브 모델을 다룹니다.
엔진
scripts/tekton.py (Python 3, pyyaml). 온톨로지는 references/ontology.md에 있습니다.
python3 scripts/tekton.py validate <model.arch.yaml> # 무결성 검사
python3 scripts/tekton.py lint <model.arch.yaml> # v0.2 — 적합성 함수; 위반 시 exit 1
python3 scripts/tekton.py stats <model.arch.yaml> # 노드/엣지/상태/규칙 개수
python3 scripts/tekton.py views # 6개 뷰 목록
python3 scripts/tekton.py mermaid <model.arch.yaml> <view># 원시 mermaid (임베드/에이전트용)
python3 scripts/tekton.py render <model.arch.yaml> [-o out.html] # 브랜드에 맞는 HTML 뷰어
python3 scripts/tekton.py query <model.arch.yaml> <from> <to> # 계층 간 경로
v0.2 온톨로지 업그레이드 (아키텍처 검토 기반)
- 포함 관계(Containment) — 모든 노드의
parent:+boundary유형; 뷰어는 중첩 그룹을 렌더링하며, 더블 클릭으로 접기/펼치기 (C4 스타일 드릴다운). - 라이프사이클(Lifecycle) — 노드의
status:(current|target|deprecated; target은 점선으로 렌더링 = 단일 모델의 현재/목표 상태) 및 결정에 대한 전체 Nygard ADR 필드 (context,consequences,status,supersedes). - 품질(Qualities) —
qualities:블록; NFR은 요소를constrains; 세부 정보 패널- 전용 뷰에 표시됩니다.
- 적합성 함수(Fitness functions) —
rules:블록 (forbid-dep,no-cycle,layer-order);tekton lint는 CI 게이트로 사용 가능 (exit 1). 설계 루프의 독립적인 검증기입니다.
에이전트가 설계 세션에서 이를 사용하는 방법
- 모델 찾기/생성하기:
<project>/docs/design/<name>.arch.yaml(또는 임시 작업용examples/). - 생각하면서 변경하기 — 대화 중에 구성 요소, 흐름, 데이터, 인프라, ADR이 드러나면 YAML에 직접 노드, 엣지, 결정을 추가/조정합니다.
- 각 실질적인 편집 후
validate+lint실행 (끊어진 참조, 잘못된 유형, 적합성 규칙 확인). render, 그리고 뷰어가 올바르다고 주장하기 전에 지오메트리 감사를 실행합니다:bash tests/visual-audit.sh <model.arch.yaml>. 이 스크립트는 모든 뷰를 헤드리스로 렌더링하고 노드 겹침이나 빈 캡처가 있으면 실패합니다. 이 감사 없이 "다이어그램이 정확합니다"라고 주장하는 것은 첫 번째 실제 사용에서 발견된 정확한 오류입니다 (연결되지 않은 그룹 내 엣지, 중복 노드 — DOM 개수 프로브로는 보이지 않고 지오메트리로만 발견됨). URL에#<view>를 추가하여 뷰에 딥 링크합니다.- **
query**를 사용하여 추적 가능성 질문("이것이 무엇에 영향을 미치는가?")에 답하고 추측을 피합니다. - 조정 → 반복. 사람이 YAML이나 뷰어 의도를 편집합니다. git diff가 전달 핸드오프입니다.
알려진 잔여 시각적 문제 (감사 실패 아님): 여정 루프백 엣지는 ELK가 임의의 단계에서 사이클을 끊게 만듭니다 (루프는 어딘가에서 끊어져야 함). 인접한 병렬 엣지 레이블은 밀집된 그룹에서 가깝게 위치할 수 있습니다.
규칙
- 모델 파일:
*.arch.yaml. 렌더링된 뷰어:*.view.html(gitignore 또는 커밋 — 선택 사항). - 경계가 있는 시스템당 하나의 모델.
external노드 +uses엣지로 시스템 연결. - 결정(ADR)은 일급 노드입니다 — 결정이
govern하는 항목에 연결합니다. - 카테고리-C HTML 보고서는 모델의 다운스트림 내보내기가 되며, 진실의 근원이 아닙니다.
렌더링 — Mermaid를 사용하지 않는 이유
기본 뷰어는 사용자 정의 렌더러이며 Mermaid가 아닙니다. Mermaid의 테마 한계로는
Broomva 디자인 시스템(OKLCH 블루 축, 무광 카드, 조건부 유리, 혜성 광택)을 표현할 수 없고,
밀집된 그래프에서는 dagre 레이아웃 성능이 저하됩니다. 대신: elkjs가 브라우저 내에서
레이아웃을 계산하고(순수 JS → 출력은 단일 자체 포함 HTML 파일로 유지됨), 노드는
Broomva 무광 카드로 그려집니다(유리는 "조건부 유리" 규칙에 따라 떠다니는 세부 정보 패널에만 사용됨).
디자인 토큰은 Broomva 디자인 시스템에서 인라인됩니다.
tekton mermaid는 일회성 임베드/에이전트가 읽을 수 있는 대상으로만 유지됩니다.
로드맵 (v0 → v2)
- v0.2 (현재): YAML 모델 · validate + lint (적합성 함수) · 6개 뷰 · 브랜드에 맞는 elkjs 뷰어 (포함 관계 접기/펼치기, 현재/목표 상태, 클릭하여 추적, 유리 세부 정보 패널) · 계층 간 쿼리 · Mermaid 폴백 임베드.
- v1: 양방향 라운드트립 (뷰어에서 끌어서 편집 → YAML로 직렬화); MCP 서버 (검증된 변경이므로 에이전트가 유효하지 않은 모델을 내보낼 수 없음); React-Flow 대화형 캔버스를 위한 전체 Broomva 디자인 시스템 벤더링.
- v2: CRDT (loro) 실시간 인간↔에이전트 공동 편집; Prosopon에 라이브 동기화하여 표면으로 제공.
상태
v0 실제 사용 — 내부 설계 도구. 설계 루프가 3개 이상의 실제 시스템에서 사용된 후 (3의 법칙) Skillify(테스트 및 등록)됩니다.