Agent에게 다이어그램 및 조작 가능한 UI를 제공하는 'dev-process-kit' 제작기

서론

Agent와의 대화에서 다이어그램과 조작 가능한 UI를 통해 인간의 인지 부하를 줄이고 원활한 피드백 루프를 지원하는 'dev-process-kit'을 만들었으니 소개합니다!

동기 부여

코딩 Agent의 개발 프로세스 참여는 빠르게 진행되고 있으며, 단순히 코드를 작성하게 하는 것을 넘어 설계, 리서치, Plan, PDM 작업 등 맡기는 영역이 날마다 늘어나고 있습니다. 그 결과 'Agent가 내놓은 아웃풋을 받아 적절성을 판단하는' 시간의 비율이 증가하고 있습니다.

인간 측의 인지 부하 병목 현상과 컨텍스트 엔지니어링

LLM은 스테이트리스(stateless)하며, 세션마다 컨텍스트가 휘발됩니다. 과거의 문맥이나 암묵지를 매번 잊고, 매번 백지 상태에서 리포지토리나 설계에 임하기 때문에 컨텍스트 엔지니어링이나 Agent의 하네스(harness)에 주목해 왔습니다.

반면 인간 측은 어떨까요?

현재 시점에서의 위임 정도는 프로젝트나 개인에 따라 다를 수 있지만, 거시적으로 볼 때 인간의 이해나 인지가 병목이 되기 때문에 다음과 같은 방향으로 나아가고 있다고 생각합니다.

• 인력의 코드 리뷰가 사라지는 방향
• 구현자 자신의 이해도 역시 더 추상적인 정책 등 AI가 내놓은 Output을 신뢰하는 쪽으로
• 코드의 품질, 제품 품질을 유지하기 위한 시스템에 투자하여 확장해 나가는 방향

결과적으로 리포지토리의 코드베이스에 대한 암묵적인 이해도(이쯤에 저 구현이 있고, 여기는 분명 이런 형태로 구현되었어야 하는데... 등)가 떨어지고 있다고 느낍니다. 특히 Agent에게 전적으로 맡기기 쉬운 취미 프로젝트 등에서 두드러지며, 판단을 요구받아도 '애초에 원래는 어떻게 되어 있었지?'라는 것을 이해하는 것부터 시작하는 경우가 늘어나고 있으며, 앞으로도 이 경향은 강해질 것입니다.

이 상태는 인간 측 역시 LLM과 비슷한 상태(백지 컨텍스트에서 필요한 것을 그때그때 탐색하는)에 가까워지고 있다고 생각합니다.

인간의 컨텍스트 길이 또한 유한하고, LLM과 비교했을 때 장문 이해가 매우 약하기 때문에 인간 특유의 컨텍스트 엔지니어링을 의식하는 것이 중요해졌습니다.

인간의 인지 모델은 개인에 따른 차이도 크겠지만,

• 장문을 통째로 읽어 소화하는 것이 어려우므로, (정확도가 다소 떨어져도) 정보가 필터링되어 논지가 좁혀진 텍스트여야 하고
• 그림을 통한 이해에 능하고, 말로 설명되는 것보다 익숙한 포맷으로 제공됨으로써 이해가 진행된다는 점이 공통적으로 이야기할 수 있습니다.

전자에 대해서는 일본어의 문체나 구조에 접근하는 방법론이 알려져 있습니다.

dev-process-kit은 후자에 접근하는 툴로, Agent가 인간과 소통할 때 알기 쉬운 다이어그램을 수행하도록 지원합니다.

dev-process-kit이란?

dev-process-kit은 Agent에게 인간 친화적으로 최적화된 컨텍스트와 페이퍼 원(paper one)의 HTML을 생성하여 제시하는 것을 돕는 도구입니다.

내용물은 Web Components로 구성되어 있어, npm 등이 필요 없고 script tag 로드만으로 작동합니다. Markdown에 대한 Mermaid 등과 모델은 가깝고, Agent는 Web Components와 DSL적으로 그려야 할 데이터를 담기만 하면 사전에 준비된 다이어그램이나 보드를 그릴 수 있습니다.

dev-process-kit이 제공하는 컴포넌트는 인간 측에서도 직접 만져서 조작할 수 있습니다.

조작한 로그가 Draft Action으로 브라우저에 기록되며, Agent에게 수정 요청으로 텍스트로 전달할 수 있습니다.

이를 통해 인간 측에서 감지한 인지 격차도 원활하게 Agent에게 전달할 수 있습니다.

dev-process-kit에서는 많은 컴포넌트를 제공하지만, 일관되게 다음과 같은 흐름을 제공합니다.

• 대상 작업 등에서 공유해야 할 전제 지식, Agent 측의 이해를 인간이 받아들이기 쉬운 형태로 제시하는 것
• 인간 측의 판단(변경 Draft Action 또는 코멘트)을 Agent에게 되돌려주는 것

다른 선택지와의 비교

vs Markdown + Mermaid / PlantUML

Mermaid나 PlantUML은 데이터를 작성하여 그림을 엔진에 맡기는 점에서 발상이 가깝습니다.

다만, Mermaid는 사람이 손으로 작성하는 것을 전제로 하여 표기법의 간결성을 우선하고 있습니다. 따라서 표현력에 제약이 있어

• 상호작용(interaction)이 있는 UI를 구성하거나
• 주석이나 UI 조작 같은 표현은 할 수 없습니다.

만약 글을 쓰는 사람이 Agent라면, 입력 데이터가 다소 장황해도 문제없기 때문에, 그보다는 인간에게 인지 부하가 낮고 직관적으로 전달하기 쉬운 표현력을 갖는 것이 중요합니다.

vs Agent에게 순수 HTML을 작성하게 할 경우

LLM에 'HTML로 도해해 줘'라고 요청하면 화면을 만들어 줄 수 있고, 도해용 Skill(예: Anthropic의 eli5) 등도 공개되어 있어 간단한 케이스라면 그것도 충분히 유력하다고 생각합니다.

dev-process-kit 측의 장점은 다음과 같습니다.

• 예를 들어 'USM을 작성해 줘'라고 했을 때 기대하는 형식이 한 번에 전달된다는 점입니다.
• 화면상의 조작 → 피드백 메커니즘을 매번 만들 필요가 없습니다. 따라서 안정적인 품질의 아웃풋을 빠르게 얻을 수 있습니다.
• 체감상으로는 구조를 포함하여 만들기 어렵고, 설령 만들어진다 하더라도 구조 측면의 HTML Output으로 불필요하게 Context를 소모하는 것을 피할 수 있으며, 본래 하고 싶었던 공통 이해(common understanding)를 만드는 데 집중할 수 있다는 점입니다 (Agent 입장에서도 Web Components + JSON만 작성하면 되므로 쉽습니다!).

반대로 말하자면, 단방향의 아웃풋만 보여주면 충분하거나 Output Format에 까다로운 요구사항이 없는 경우에는 Plain HTML도 괜찮다고 생각합니다.

구조(Mechanism)

dev-process-kit은 도입 장벽을 낮추기 위해 빌드 불필요 및 설치 불필요한 Web Components로 설계되었습니다.

배포: jsDelivr를 통한 ESM 전송

npm install이나 빌드 설정이 필요 없습니다. HTML 안에 <script type="module">만 한 줄 작성하면 작동합니다.

<script
type="module"
src="https://cdn.jsdelivr.net/npm/[email protected]/dist/templates/usm.js"
...

Web 표준의 Custom Elements로 만들어졌기 때문에 특정 UI 프레임워크에 얽매이지 않습니다.

Agent는 JSON으로 데이터를 작성하고, 템플릿이 그리는 방식

Agent가 출력하는 HTML 파일은 다음과 같은 구조를 가집니다.

<!DOCTYPE html>
<html lang="ja">
<head>
...

1개의 파일로 하나의 웹페이지로서 완결됩니다. 로컬에서 직접 열거나, 사람에게 파일을 전달하거나, Claude Artifacts 등에서 공개하는 것도 가능합니다.

사용 방법(Usage)

Skill을 공개하고 있으므로 스킬과 함께 'USM을 작성해 줘'처럼 다이어그램을 지정하여 요청하기만 하면 됩니다.

Skill 도입

사용 환경에 맞춰 Skill을 추가합니다.

Agent Skills 규격에 준하는 CLI의 경우:

npx skills add d-kimuson/dev-process-kit

Claude Code의 경우:

/plugin marketplace add d-kimuson/dev-process-kit
/plugin install dev-process-kit@dev-process-kit

Skill을 설치하지 않고 시도하는 경우

Skill을 넣지 않아도 GitHub의 raw URL을 프롬프트에 첨부하기만 하면 시도할 수 있습니다.

https://raw.githubusercontent.com/d-kimuson/dev-process-kit/main/skills/dev-process-kit/SKILL.md를 따르세요.

Claude Artifacts에서의 이용

Claude Code에서 페이지를 Claude Artifacts로 공개하면, 리뷰란에 'Claude에게 보내기(Claude に送る)' 버튼이 표시됩니다.

이는 Claude Artifact에 탑재된 메시지 전송 기능을 활용하는 것으로, 복사해서 Claude를 다시 열고 보내는 수고를 덜어줍니다. Agent는 메시지를 받으면 자동으로 수정하여 재공개합니다.

지원하는 템플릿과 컴포넌트

v0.0.6 버전에서 제공하는 템플릿과 컴포넌트입니다.

실제는 샘플 카탈로그(Sample Catalog)에서 확인할 수 있습니다.

템플릿 (Template)

합의하고 싶은 목적에 따라 다르게 사용합니다.

컴포넌트 (Component)

템플릿 내부나 <dpk-template-plain>에 배치할 수 있는 다이어그램 컴포넌트입니다.

• 상태 전이도 (dpk-component-state-machine)
• 시퀀스 다이어그램 (dpk-component-sequence)
• 의존 그래프 (dpk-component-dependency-graph)
• ER 다이어그램 (dpk-component-er): 두 스키마 간의 차이점 표시 지원
• 아키텍처 맵 (dpk-component-architecture-map)
• 마인드맵 (dpk-component-mindmap)
• 칸반 (dpk-component-kanban)
• Formal Spec (dpk-component-formal-spec): 검증된 속성을 쉬운 말로 설명

다이어그램의 각 요소에도 브라우저에서 직접 코멘트를 달 수 있습니다. 마인드맵이나 칸반은 노드의 추가나 편집도 지원하며, 그 차이점 역시 부모 템플릿의 수정 요청에 통합됩니다.

설계 (Design)

페이지 구성 모델 (Page Composition Model)

페이지 상태는 다음 모델로 표현됩니다.

Page = Base Data（HTML에 내장된 JSON）
+ Template（의미 모델 및 조작어휘）
+ Draft Actions（인간의 수정 요청. LocalStorage에 저장）
...

템플릿이 도메인의 의미(단계나 카드 정의, 허용되는 조작)를 담당하고, Agent는 HTML 내부 데이터(JSON)를 유지하는 역할 분담 구조입니다.

외부로 공개되는 인터페이스는 Custom Elements, HTML 속성, DOM 속성, DOM 이벤트, 슬롯(slots)이라는 웹 표준 메커니즘으로 한정했습니다. 내부 구현에 Lit을 사용하고 있지만, 외부에서는 보이지 않는 구현 세부사항으로서 캡슐화되어 있습니다.

상쇄되는 조작의 자동 정리 (Automatic Cleanup of Counteracting Operations)

카드를 추가했다가 바로 삭제하거나, 다른 곳으로 옮겼다가 원래대로 되돌리는 등의 조작은 빈번하게 발생합니다.

이러한 조작들을 그대로 Agent에게 전달하면, 불필요한 지시로 컨텍스트를 소모하게 됩니다.

따라서 dev-process-kit에서는

개별적인 조작(operation)마다의 역조작 규칙을 정의하는 것이 아니라, 결과의 동일성으로 판정하기 때문에 필요한 변경 사항을 실수로 지울 염려가 없습니다. Agent에게는 순수한 차이점(net diff)만 전달되는 구조입니다.

오래된 수정 요청 보호

Agent가 HTML을 재작성한 결과, 대상 요소가 삭제되어 적용할 수 없게 된 수정 요청은 임의로 폐기하지 않고 stale (무효) 상태로 회색 처리하여 남겨두고, 그 이유(예: target-missing)를 표시하는 방식입니다.

요약(brief)에서도 ## Not applicable to the current base와 같이 별도의 영역에 출력되므로, Agent가 오래된 지시사항을 이중으로 적용하는 사고를 막을 수 있습니다. 이미 반영된 수정 요청은 새로운 HTML이 로드될 때 자동으로 삭제됩니다.

다이어그램 편집 조작의 통합

템플릿 안에 배치한 마인드맵이나 칸반 같은 편집 조작도, 외부 템플릿의 수정 요청(Draft Actions)으로 자동 통합되는 설계입니다.

리뷰란과 요약(brief)이 하나로 통일되므로, 템플릿과 다이어그램 변경을 따로 처리할 필요가 없습니다. 다이어그램 컴포넌트 자체가 조작을 재생하고 결과를 보고하기 때문에, 템플릿 측은 내부에 배치된 다이어그램의 상세 내용을 알 필요가 없는 구조입니다.

용도별 진입점(Entry Point)

배포 스크립트는 사용 목적에 따라 분리되어 있습니다.

• templates/<name>.js: 특정 템플릿만 사용할 경우
• components.js: 다이어그램 컴포넌트만 사용할 경우
• index.js: 모든 기능을 포함한 올인원(all-in-one)

필요한 컴포넌트만 로드함으로써 통신량과 렌더링 부하를 줄일 수 있습니다.

마무리

Agent의 다이어그램 구현과 원활한 피드백 루프를 지원하는 'dev-process-kit'을 소개했습니다!

최근 프로덕트 개발에서도 Agent와의 텍스트 커뮤니케이션이 인지 부하(cognitive load)로 느껴져 힘들어지기 때문에, 이 키트를 사용하고 있는데 일반 텍스트에 비해 대화하기 훨씬 수월해졌다고 느낍니다.

Agent가 자율적으로 프로덕트를 진행하는 측면이 강해질수록, 판단을 위해 인간 측의 사전 지식이나 인지를 보완하는 컨텍스트 엔지니어링(context engineering)의 필요성이 커진다고 생각하므로 추천합니다.

관심이 있다면, 아래와 같이 직접 Agent에게 전달하여 사용해 보세요!

https://raw.githubusercontent.com/d-kimuson/dev-process-kit/main/skills/dev-process-kit/SKILL.md 에 따라.
이 프로덕트의 USM을 만들어줘.

토론(Discussion)