AI가 작성한 문서에 직접 댓글을 달고 싶어서 VS Code 확장 프로그램을 만들었습니다

Agentic HTML Visual Editor를 소개합니다. 이 VS Code 확장은 AI 에이전트가 작성한 문서를 읽고 편집하며, 댓글을 통해 피드백을 주고받을 수 있게 해줍니다.

서론

코딩 및 문서화 작업을 AI 에이전트에게 더 많이 맡기면서, 제 작업 방식에 변화를 느꼈습니다. 제가 직접 글을 쓰는 시간보다 그들이 작성한 것을 읽고 검토하는 시간이 더 많아졌다는 것입니다.

이러한 문서를 계속 검토하면서, 변경 사항을 요청하는 과정 자체가 부담으로 다가왔습니다. 연구 보고서나 디자인 노트에서 무언가를 수정하고 싶을 때마다, 채팅창에 관련 구절을 인용하고 무엇을 원하는지 설명해야 했습니다. 제가 읽고 있는 바로 그 위치에 피드백을 남길 수 있다면 얼마나 좋을까 생각했습니다.

이러한 고민 끝에 Agentic HTML Visual Editor를 만들게 되었는데, 이 VS Code 확장은 HTML 파일을 편집 가능한 문서로 열어줍니다. 텍스트를 선택하고 댓글을 추가할 수 있습니다. 댓글과 답글은 HTML 파일 내부에 저장됩니다. 함께 설치하는 Agent Skill을 사용하면 AI 에이전트에게 해당 파일을 읽고, 제 피드백에 따라 문서를 수정하며, 같은 스레드에서 답변하도록 요청할 수 있습니다.

이 디자인 노트에서 에이전트는 '팀 검토(team review)'에 대한 질문을 첨부했고, 인간 사용자는 같은 스레드에서 답변했습니다. 파일을 다시 열어도 그 설명은 관련 텍스트 옆에 그대로 남아있습니다.

변경 요청할 때마다 텍스트를 복사해야 했습니다

제가 피하고 싶었던 작업의 구체적인 예시입니다. 예를 들어, 체크아웃 디자인 노트를 검토하다가 팀 검토 날짜를 명확히 하고 싶다고 가정해 봅시다. 이를 채팅창에서 요청하려면, 검토 날짜가 언급된 구절을 인용하고 언제 이루어져야 하는지 설명해야 합니다.

요청 자체가 짧더라도, 이 방식은 사용자가 문서에서 텍스트를 복사하고 에이전트가 파일 내 해당 텍스트를 찾아야 하는 과정을 필요로 합니다. 이는 긴 문서나 유사한 설명이 여러 곳에 나타날 때 특히 불편해집니다.

또 다른 문제는 논의 내용이 문서와 분리된다는 것이었습니다. 피드백과 결정 사항은 채팅 기록에 남아 있었지만, 텍스트에 통합되거나 파일에 기록되지 않는 한, 문서를 혼자 읽는 사람은 어떤 내용이 논의되었는지 알 수 없었습니다.

더 나은 접근 방식을 시사한 경험은 Claude Code의 Plan 모드에서 생성된 구현 계획에 직접 피드백을 남기는 것이었습니다. 저는 일상적인 연구 보고서와 디자인 노트에도 동일한 접근 방식을 사용하고 싶었습니다.

피드백이 첨부된 가독성 높은 HTML

추가하고 싶었던 기능은 해당 문서를 직접 편집하고 피드백과 답글을 같은 파일에 보관하는 방식이었습니다. 그래서 표시된 텍스트를 선택하고 댓글을 첨부할 수 있도록 만들었습니다. 선택된 텍스트는 피드백이 적용되는 정확한 위치를 식별하므로, 원하는 변경 사항에 초점을 맞춰 댓글을 달 수 있습니다.

에이전트는 디자인 노트의 다른 곳에도 유사한 문구가 나타나더라도, 해당 구절 옆에 있는 피드백을 읽을 수 있습니다. 또한 직접 텍스트 편집기에서 텍스트를 수정하여 스스로 변경 사항을 만들 수도 있습니다.

편집이나 댓글로 의도가 기록되면 파일을 저장하고 에이전트에게 “변경 사항을 적용했으니 검토해 주세요”라고 말하며 HTML 파일을 읽도록 요청할 수 있습니다. 파일에 변경의 위치와 의도가 모두 포함되어 있기 때문에, 채팅 요청을 짧게 유지하는 것이 목표였습니다.

같은 문서에서 변경 사항 검토하기

피드백을 남긴 후 다음 단계는 에이전트가 변경 사항을 적용하고 그 결과를 검토하는 것입니다. 문서 생성부터 수정 사항 확인까지의 워크플로우는 다음과 같습니다:

1. AI 에이전트에게 연구 보고서나 디자인 노트 작성을 HTML 파일 형태로 요청합니다.
2. 확장 프로그램에서 파일을 열고 텍스트를 편집하거나 구절을 선택하여 댓글을 남깁니다.
3. 에이전트에게 저장된 파일을 읽고, 댓글에 답장하며 문서를 수정하도록 요청합니다.
4. 같은 문서를 다시 열어 답장과 수정을 검토합니다.

결과를 검토할 때, 에이전트의 답장을 원래 댓글 스레드에서 확인할 수 있습니다. 더 많은 피드백이 있다면 해당 스레드에 답장하고 에이전트에게 파일을 다시 읽도록 요청하면 됩니다.

답장과 함께 문서에서 정확히 무엇이 변경되었는지도 보고 싶었기 때문에, 삽입 및 삭제 표시(insertion and deletion marks)를 지원하도록 추가했습니다. 에이전트가 제안하는 변경 사항을 표시할 때, 편집기에서 이를 검사하고 수락하거나 거부할 수 있습니다.

앞서 소개된 Agent Skill은 HTML 작성, 댓글 답장, 그리고 변경 표시를 모두 다루므로, 에이전트는 응답과 제안된 편집 내용을 사용자가 편집기에서 검토할 수 있는 형태로 기록할 수 있습니다.

콘텐츠 생성 및 스타일시트 재사용

문서 생성을 간단하게 유지하기 위해, 이 확장 프로그램은 제목(headings), 표(tables), 목록(lists)을 위한 스타일시트를 포함합니다. 에이전트가 HTML 콘텐츠를 작성하고, 편집기에서 스타일링을 제공합니다. 이 스타일시트는 확장 프로그램 내부에서 적용되며, 저장된 파일을 일반 브라우저에서 열 경우 사용자가 직접 CSS를 공급하지 않는 한 브라우저의 기본 스타일링을 사용합니다.

시작하기

Visual Studio Marketplace에서 확장 프로그램을 설치하고, HTML 파일을 열어 “WYSIWYG로 열기(Open in WYSIWYG)”를 선택하여 편집 가능한 문서로 확인합니다.

확장 프로그램이 설치되면, AI 에이전트를 위한 작성 스킬(authoring skill)을 설치해야 합니다:

npx skills add Ymmy833y/Agentic-HTML-Visual-Editor

소스 코드, README 및 작성 스킬은 GitHub 저장소에서 확인할 수 있습니다.

만약 연구 보고서나 디자인 노트와 같은 자료로 AI 에이전트와 작업하면서 채팅창에 특정 구절을 반복적으로 인용하는 자신을 발견한다면, 이 접근 방식을 시도해 보시길 바랍니다.