Effective HTML로 탐색하는 아키텍처 문서 만들기

아키텍처 문서는 구성요소의 관계를 보여주고 독자가 실제 코드를 찾을 수 있게 해야 합니다. 로그인 요청을 설명한다면 브라우저, API와 저장소의 연결뿐 아니라 성공·실패 조건과 관련 파일도 함께 제시합니다.

Effective HTML은 에이전트가 프로젝트 자료를 바탕으로 브라우저에서 탐색하는 HTML 문서를 만들도록 돕는 프로젝트입니다. AI 카페인이 소개한 예시에서는 독자가 구성요소를 선택해 역할과 요청 흐름을 읽을 수 있습니다. 문서 작성자는 연결선과 상세 설명을 실제 호출자, 라우트, 설정과 대조해야 합니다. 이 글에서는 로그인 구조를 설명하는 요청 예시와 생성 문서의 확인 절차를 설명합니다.

참조할 지침과 만들 문서

Effective HTML 저장소는 HTML 산출물을 만드는 스킬과 참고 지침을 제공합니다. 아키텍처 관계에는 html-diagram 지침을 참조할 수 있습니다. 저장소는 설치 없이 참고 자료로 읽는 방식도 안내합니다. 에이전트가 스킬을 사용하는 환경이라면 다음 명령으로 필요한 스킬을 추가할 수 있습니다.

npx skills add plannotator/effective-html --skill html-diagram

생성 요청에는 독자, 설명할 흐름, 읽을 코드, 결과 파일, 확인할 조작을 적습니다. 로그인 구조를 설명하는 요청은 다음처럼 구성할 수 있습니다.

새 개발자가 로그인 요청의 성공과 실패 경로를 이해할 수 있는
architecture.html을 작성해주세요.
로그인 라우트, 세션 처리 코드, 사용자 저장소 호출을 먼저 읽어주세요.
첫 화면에는 브라우저·API·사용자 저장소의 관계를 표시해주세요.
노드를 선택하면 책임, 입력과 출력, 관련 파일을 보여주세요.
성공 경로와 인증 실패 경로를 구분하고 확인 못 한 연결은 추정으로 표시해주세요.
외부 스크립트와 폰트 없이 열 수 있게 하고 키보드로 노드를 선택할 수 있게 해주세요.

HTML을 만든 뒤에는 브라우저에서 노드를 선택하고 성공·실패 경로를 각각 조작합니다. 상세 설명의 주소와 함수명이 현재 코드와 맞는지도 대조합니다.

직접 작성한 로그인 흐름과 예시 파일 경로입니다. 실제 저장소의 구조가 아닙니다. 그림에는 문서의 각 구성요소를 어떤 코드 위치와 연결할지 표시했습니다.

첫 화면과 구성요소의 상세 설명

처음 보는 시스템에서는 주요 구성요소를 한 화면에서 파악할 수 있어야 합니다. 프런트엔드, API, 데이터베이스, 외부 서비스처럼 역할이 다른 부분을 구분하고 연결의 방향을 표시합니다.

문서 작성자는 독자가 구성요소를 선택했을 때 책임과 인터페이스를 확인할 수 있도록 설명을 작성합니다. 어떤 요청을 받고, 무엇을 반환하며, 어느 부분에 의존하는지 보여주면 됩니다. 이름만 나열하기보다 실제로 확인할 파일과 함수도 함께 적으면 독자가 설명을 코드와 대조할 수 있습니다.

첫 화면에 모든 함수를 표시하면 주요 구성요소의 관계를 읽기 어려워질 수 있습니다. 먼저 서비스나 모듈 수준에서 보여주고 필요한 위치에서 세부 내용을 펼치는 방식이 적합할 수 있습니다. 문서의 목적이 신규 개발자 안내인지 특정 장애 분석인지에 따라 설명 범위를 정합니다.

성공과 실패의 요청 경로

로그인 요청을 설명한다면 브라우저에서 API를 호출하고 서버가 사용자를 확인한 뒤 응답하는 경로를 보여줄 수 있습니다. 이때 인증 실패, 세션 만료, 외부 서비스 오류처럼 경로가 달라지는 조건도 구분해야 합니다.

흐름 애니메이션에는 실제 요청을 관찰한 결과인지 문서에서 재생하는 예시인지 표시합니다. 실제 관찰이라면 사용한 환경과 요청 조건도 남겨야 합니다.

코드에서 확인하지 못한 관계는 추정으로 표시합니다. 문서의 빈 부분을 에이전트가 자연스럽게 채웠더라도 사실로 채택하면 안 됩니다. 실제 호출자, 라우트, 설정과 대조해 근거를 보완합니다.

오프라인 HTML의 의존성

하나의 HTML 파일을 전달할 때도 외부 스크립트, 폰트, 이미지, API 호출이 포함됐는지 살펴봅니다. 오프라인으로 전달하려면 필요한 자산을 파일 안이나 함께 전달할 폴더에 포함해야 합니다.

네트워크 없이 문서를 열고 노드 선택과 요청 경로 표시를 실행해봅니다. 외부 요청이 필요한 부분은 오프라인에서 쓸 수 있는 범위와 구분하고, 내부 경로나 비공개 주소가 전달 파일에 포함되지 않았는지도 확인합니다.

현재 코드와 문서를 비교하기

생성 후에는 주요 연결을 코드에서 확인합니다. 문서에 표시한 API가 존재하는지, 사용한 이름이 현재 코드와 같은지, 삭제된 모듈이 남아 있지 않은지 점검합니다. 대표 요청을 실제로 실행할 수 있다면 응답과 화면의 흐름도 비교합니다.

시각적 검토에서는 확대와 축소, 선택 상태, 좁은 화면, 키보드 조작을 확인합니다. 색상만으로 역할을 구분하지 않도록 이름과 설명도 제공합니다. 애니메이션을 줄이는 환경에서도 핵심 관계를 읽을 수 있어야 합니다.

문서에는 작성 시점과 확인한 코드 버전을 남깁니다. 로그인 라우트나 세션 처리 코드가 바뀌었다면 해당 노드의 이름과 연결, 성공·실패 경로를 다시 대조할 수 있습니다.

문서의 확인 기준은 독자가 대표 요청의 경로와 실패 조건을 찾고, 설명의 근거가 되는 코드로 이동할 수 있는지입니다. 설명이 부족한 노드는 책임, 입출력과 코드 위치를 보완한 뒤 조작을 다시 확인합니다.