# HTML Brief

> 근거를 읽고 판단하거나 공유하기 위한 짧은 단일 HTML 문서를 만든다. 사용자가 “내부 의사결정 문서”, “대표 전달용 HTML”, “조사 결과를 HTML 보고서로”, “나를 위한 개발 보고서”, “출처가 있는 HTML 정리”를 요청할 때 사용한다. 랜딩 페이지·제품 UI·웹앱 구현이나 단순 Markdown 변환에는 사용하지 않는다.

- Skill: `gagip/html-brief` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add gagip/html-brief`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gagip/html-brief/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: gagip (https://skillmd.com/u/gagip)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gagip/html-brief

---


# html-brief

조사·검토 결과를 **사람이 빠르게 읽고 AI가 근거를 다시 확인할 수 있는 단일 HTML 문서**로 만든다.

이 스킬은 예쁜 웹페이지를 만드는 스킬이 아니다. 독자가 문서를 처음 열었을 때 아래 세 가지가 분명해야 한다.

1. 결론 또는 결정할 내용이 무엇인가.
2. 그 판단을 바꾸는 핵심 근거와 제약은 무엇인가.
3. 원문을 어디서 다시 확인할 수 있는가.

## 적용 범위

- **의사결정 모드**: 수신자가 선택·승인·제외 범위를 결정해야 할 때.
- **보고 모드**: 조사, 기술 검토, 작업 결과를 본인이나 내부 수신자가 이해하고 재사용해야 할 때.

다음에는 적용하지 않는다.

- 마케팅 랜딩 페이지, 제품 화면, 대시보드, 웹앱
- 사용자가 HTML을 요구하지 않은 일반 대화 답변
- 내용 구조는 그대로 두고 파일 형식만 바꾸는 단순 변환

## 모드 선택

독자가 문서를 읽고 **무엇인가를 골라야 하면 의사결정 모드**, 결론과 근거를 **이해하거나 후속 작업에 사용하면 보고 모드**다. 모호하면 독자에게 요구되는 행동을 기준으로 판단하고, 결과물에 선택한 모드를 표시한다.

두 모드의 필수 구조와 `brief-data` JSON 형식은 [references/modes.md](references/modes.md)를 읽고 따른다.

## 작성 원칙

### 결론부터 쓴다

첫 화면에 제목, 한 문장 결론, 수신자, 기준일을 둔다. 조사 과정이나 배경 설명으로 시작하지 않는다. 문서 전체의 중심 문장은 하나만 정하고 나머지는 그 문장을 입증하거나 실행하는 정보로 제한한다.

### 사실·해석·권고를 구분한다

- **사실**: 원문으로 확인 가능한 내용. 가까운 위치에 출처 ID를 붙인다.
- **해석**: 여러 사실에서 도출한 판단. “이 문서의 해석”임을 드러낸다.
- **권고**: 비용·위험·효과를 비교해 제안한 행동. 판단 기준을 함께 쓴다.

시점에 따라 달라질 수 있는 사실은 현재 제공된 웹 검색·페이지 읽기 도구로 다시 확인한다. 공식 문서·법령·제품 원문 같은 1차 자료를 우선하고, 실제로 연 URL과 확인일을 남긴다. 근거가 부족하면 단정하지 않고 한계를 적는다.

### 기존 자료를 보존한다

기존 신청서·보고서·계획서를 입력으로 받았을 때는 사용자가 명시적으로 덮어쓰라고 하지 않는 한 수정하지 않는다. 날짜나 버전을 포함한 새 HTML 파일을 만들고, 결과물에 “기존 문서 보존 / 신규 문서” 여부를 표시한다.

### 읽을 가치가 있는 정보만 남긴다

수신자가 결정하거나 다음 행동을 하는 데 필요 없는 조사 로그, 장황한 배경, 비슷한 표현의 반복은 제외한다. 전문용어는 독자 수준에 맞게 처음 한 번만 풀어 쓰되, 해당 분야 독자에게 익숙한 용어를 억지로 바꾸지 않는다.

## 작업 흐름

### 1. 입력과 기존 자산 확인

현재 하네스가 읽는 프로젝트 지침 파일(`AGENTS.md`, `CLAUDE.md` 등) 중 현재 경로에 가장 가까운 적용 범위를 따른다. 기존 문서·코드·출력 위치를 먼저 확인하고, 이미 있는 템플릿을 재사용할 수 있는지도 본다.

결과물이 달라지는 핵심 정보만 확인한다.

- 수신자와 문서 목적
- 의사결정/보고 모드
- 반드시 보존할 기존 자료
- 기준일과 최신성 요구
- 출력 위치

위 정보가 문맥에서 분명하면 다시 묻지 않는다. 출력 위치만 불명확하면 프로젝트의 기존 보고서 폴더를 우선하고, 관례도 없을 때만 사용자에게 묻는다.

### 2. 근거 수집

주장마다 필요한 근거 수준을 정하고, 최신성이 필요한 내용은 원문을 확인한다. 여러 출처가 같은 사실을 반복하면 가장 직접적인 1차 자료만 남긴다. 사양·법·정책처럼 버전이 중요한 자료는 문서 버전과 확인일을 기록한다.

내부 코드나 파일이 근거라면 실제 경로와 값을 확인한다. 팀 공유 문서에는 수신자가 접근할 수 없는 로컬 경로를 근거로 넣지 않고, 필요한 사실을 문서 안에 자족적으로 설명한다.

### 3. 정보 구조 결정

[references/modes.md](references/modes.md)의 해당 모드를 기본 골격으로 사용한다. 모든 절을 기계적으로 채우지 말고 내용이 없는 절은 제거한다.

관계가 셋 이상이거나 비교가 반복될 때만 시각화를 쓴다.

- 항목 × 속성 비교: 표
- 시간·측정·업무 순서: 흐름 또는 타임라인
- 한 원인이 여러 결과에 미치는 영향: 연결도
- 수치 비교: 단순 막대 또는 숫자 카드

장식용 차트와 아이콘은 넣지 않는다.

### 4. HTML 작성

[assets/brief-template.html](assets/brief-template.html)을 출발점으로 복사해 내용에 맞게 구조를 줄이거나 확장한다. 템플릿의 색과 배치는 기본값일 뿐이며, 가독성과 의미가 좋아질 때 조정할 수 있다.

필수 조건:

- 외부 빌드 없이 열리는 단일 HTML. 필요한 CSS는 문서 안에 포함한다.
- 의미 있는 `main`, `header`, `section`, `table` 구조와 한 개의 `h1`.
- 데스크톱과 모바일에서 문서 전체에 가로 스크롤이 생기지 않는다. 넓은 표만 자체 영역에서 가로 스크롤한다.
- 인쇄 시 배경·그림자 의존 없이 읽힌다.
- 색은 역할이 있는 강조색 1~2개와 회색 계열로 제한한다.
- 이모지 장식, 그라데이션, 과장된 홍보 문구, 균일한 카드 반복을 피한다.
- 출처 ID는 주장 가까이에 두고, 하단 원문 목록의 ID와 일치시킨다.
- `<script id="brief-data" type="application/json">`에 핵심 결론·결정·출처를 기계 판독 가능하게 넣는다.
- 사용자 또는 프로젝트가 제공한 회사·개인 정보를 외부 서비스로 전송하지 않는다.

### 5. 검증

먼저 이 스킬 디렉터리를 기준으로 `scripts/validate_html.py`의 절대 경로를 구해 결과 HTML을 검사한다.

```bash
python3 /absolute/path/to/html-brief/scripts/validate_html.py /absolute/path/to/result.html
```

그 다음 가능한 로컬 브라우저나 렌더링 도구로 아래를 확인한다.

- 데스크톱 약 1440×1000: 첫 화면에서 결론과 문서 목적이 보이는가.
- 모바일 약 390×844: 본문이 한 열로 정리되고 문서 전체 가로 넘침이 없는가.
- 비교표: 모바일에서는 표 컨테이너 안에서만 스크롤되는가.
- 출처 링크와 `brief-data` JSON이 유효한가.
- 템플릿에서 가져왔지만 이 문서에서 쓰지 않는 컴포넌트 CSS가 남아 있지 않은가. 템플릿은 두 모드를 모두 담고 있어, 한 모드로 쓰면 나머지 모드의 클래스가 그대로 남는다. 클래스 이름을 본문에서 찾아 실제 사용 여부를 확인하고 쓰지 않는 규칙은 지운다.
- 기존 자료를 보존하기로 했다면 원본이 바뀌지 않았는가.

화면 검증 중 만든 캡처의 저장 위치는 프로젝트 지침을 따른다. 검증하지 못한 항목은 완료 보고에서 먼저 밝힌다.

### 6. 전달

완료 보고에는 결과물 링크, 한 문장 결론, 사용한 모드, 검증 결과만 남긴다. 출처는 HTML 안에 있으므로 대화에서 전부 반복하지 않는다. 사용자가 바로 검토할 수 있도록 가능한 경우 결과 파일을 현재 작업 화면에 연다.

## 품질 기준

좋은 결과물은 내용이 많아서가 아니라 다음 질문에 바로 답한다.

- 첫 화면만 보고도 이 문서가 무엇을 위한 것인지 알 수 있는가.
- 권고를 따르지 않을 이유까지 판단할 수 있는가.
- 주장과 출처를 AI가 ID 또는 URL로 연결할 수 있는가.
- 작은 화면과 인쇄물에서도 정보 위계가 유지되는가.
- 원본 자료와 새 해석이 섞이지 않았는가.