AI 워크플로우를 위한 HTML Artifact의 협업 기능 구현하기

최근 다음과 같은 간단한 질문을 두고 많은 논의가 이루어지고 있습니다:

AI Artifact (결과물)의 기본 형식을 Markdown으로 해야 할까요, 아니면 HTML로 해야 할까요?

Markdown은 단순하고, 읽기 쉬우며, 토큰 (Token) 효율적입니다.

HTML은 더 무겁지만, 정보를 훨씬 더 풍부한 방식으로 표현할 수 있습니다. HTML을 사용하면 Artifact에 적절한 섹션, 표 (Tables), 카드 (Cards), 콜아웃 (Callouts), 레이아웃 (Layouts), 시각적 계층 구조 (Visual hierarchy), 그리고 인터랙티브 컴포넌트 (Interactive components)까지 포함할 수 있습니다. HTML이 초기에 더 많은 토큰을 소비할 수는 있지만, 추가적인 구조와 명확성 덕분에 나중에 발생할 모호함과 반복적인 피드백 과정을 줄일 수 있습니다.

제 생각은 약간 다른 방향으로 흘러갔습니다:

만약 HTML이 AI 생성 Artifact의 주요 매체가 된다면, 어떻게 이를 협업 가능하게 만들 수 있을까?

그 지점에서 저는 공백을 발견했습니다.

업무에서 저는 Confluence를 광범위하게 사용합니다. 누군가 사양서 (Specification)를 작성하면, 다른 사람들이 특정 섹션에 댓글을 남기고, 작성자—또는 점점 더 늘어나고 있는 추세인 AI—가 나중에 그 댓글들을 처리합니다. 이 워크플로우 (Workflow)는 매우 자연스럽게 느껴집니다.

하지만 HTML Artifact의 경우, 협업이 그렇게 간단하지 않습니다.

만약 제가 특정 단락, 표의 행 (Table row), 섹션, 또는 카드에 댓글을 남기고 싶다면, 어떻게 AI에게 정확한 위치를 지시할 수 있을까요?

• "세 번째 섹션을 변경해줘"라는 말은 모호합니다.
• 텍스트를 복사해서 붙여넣는 방식은 취약합니다.
• 가공되지 않은 Raw HTML은 시각적으로 검토하기가 쉽지 않습니다.

그래서 저는 HTML Review Kit을 만들기 시작했습니다.

GitHub Repository: https://github.com/bharathnayak03/html-review-kit

HTML Review Kit이란 무엇인가?

HTML Review Kit은 정적인 HTML Artifact를 검토 가능하고 AI가 편집할 수 있도록 만들어 줍니다.

여러분은 다음과 같은 작업을 할 수 있습니다:

1. 브라우저에서 HTML Artifact 열기
2. 렌더링된 페이지의 특정 부분에 주석 (Annotate) 달기
3. 검토 댓글 (Review comments) 남기기
4. AI 코딩 에이전트 (AI coding agent)에게 직접 보낼 수 있는 프롬프트 (Prompt) 생성하기

생성된 프롬프트에는 검토 댓글과 더불어, 해당 소스 콘텐츠의 위치를 찾기 위해 필요한 타겟팅 정보 (Targeting information)가 모두 포함됩니다.

이 접근 방식은 W3C Web Annotation Data Model에서 영감을 받았습니다:

https://www.w3.org/TR/annotation-model/

타겟팅은 어떻게 작동하나요?

AI가 검토 중인 정확한 콘텐츠를 식별할 수 있도록, 이 도구는 다음과 같은 여러 타겟팅 메커니즘 (targeting mechanisms)을 캡처합니다:

• data-hrk-id
• 텍스트 인용 선택자 (Text Quote Selectors)
• CSS 선택자 (CSS Selectors)
• XPath
• 소스 파일 메타데이터 (Source file metadata)

이를 통해 AI는 소스 문서의 정확한 부분을 안정적으로 찾아내고 수정할 수 있는 충분한 문맥 (context)을 확보하게 됩니다.

워크플로우 (Workflow)

워크플로우는 다음과 같습니다:

1. HTML 아티팩트 (HTML artifact)를 생성하거나 작성합니다.
2. 이를 시각적으로 검토합니다.
3. 특정 요소 (elements)에 댓글을 남깁니다.
4. 생성된 검토 프롬프트 (review prompt)를 복사합니다.
5. AI 에이전트 (AI agent)에게 댓글 내용을 처리하도록 요청합니다.
6. 소스 HTML을 업데이트합니다.

잠재적 사용 사례 (Potential Use Cases)

HTML Review Kit은 다음과 같은 경우에 유용할 수 있습니다:

• AI가 생성한 사양서 (specifications)
• 설계 문서 (Design documents)
• 제품 요구 사항 문서 (Product requirement documents)
• 보고서 (Reports)
• 대시보드 (Dashboards)
• 지식 베이스 문서 (Knowledge-base articles)
• 풍부한 문서 (Rich documentation)
• 검토와 반복 (iteration)을 통해 이점을 얻을 수 있는 모든 HTML 기반 아티팩트

포함된 AI 에이전트 스킬 (AI Agent Skill Included)

리포지토리 (repository)에 AI 에이전트 스킬도 추가했습니다.

다음 명령어로 설치하세요:

bash npx skills add bharathnayak03/html-review-kit

설치가 완료되면, AI 코딩 에이전트 (AI coding agent)가 HTML 아티팩트를 생성할 때 html-review-kit을 사용하도록 요청하기만 하면 됩니다.

x.com

피드백을 기다립니다

이 프로젝트는 HTML을 AI 워크플로우를 위한 더욱 협업적인 매체로 만들기 위한 초기 탐색 단계입니다.

여러분의 의견을 듣고 싶습니다:

• 이것이 여러분이 겪었던 문제인가요?
• 이러한 검토 워크플로우가 여러분의 팀에 유용할까요?
• 어떤 기능이 추가된다면 더 가치 있을까요?

피드백, 아이디어 및 기여를 환영합니다.