AI 시대 사내 자료는 '리치 HTML'로 남겨야 강력하다: AWS Amplify를 활용한 인증형 내부 문서 공개
요약
AI 시대에는 기획 결과물을 Markdown 대신 리치 HTML로 남기는 것이 전달력 측면에서 훨씬 유리합니다. 특히 Tailwind가 포함된 단일 HTML은 AI 요청에 의해 쉽게 생성되며, CSS와 JS를 인라인으로 포함하여 운영의 편리성을 극대화할 수 있습니다. AWS Amplify 빌드 기능을 활용하면 모크업을 푸시할 때마다 자동으로 최신 목차 페이지를 유지할 수 있어 관리 효율성이 높습니다.
핵심 포인트
- 기획 결과물은 Markdown보다 리치 HTML이 전달력이 우수함
- AI가 생성하는 목업은 CSS/JS 인라인 단일 HTML 형태가 가장 편리함
- AWS Amplify 빌드 기능을 활용해 모크업 푸시 시 자동화된 목차 관리가 가능함
서론
AI 덕분에 코드나 문서를 대량 생산할 수 있게 되면서, 개발의 병목 지점이 '만드는 것'에서 '남기거나 공유하는 것'으로 이동했다는 것을 체감하고 있습니다.
특히 기획 단계의 결과물(UI 목업, 시스템 구성도, 전략 자료 등)은 Markdown 텍스트로 남기는 것보다 리치 HTML로 남길 때 훨씬 더 잘 전달됩니다.
본문에서는 사내 기획 리포지토리를 '인증형 HTML 포털'로 운영하면서 얻은 학습 내용을 실제 구성과 함께 정리합니다.
왜 Markdown이 아닌 HTML인가
사내 자료를 Markdown으로 작성하는 것은 간편하지만, '보여주고 의사결정하는' 상황에서는 전달력에 한계가 있습니다. 두 가지를 나란히 놓고 비교하면 차이가 명확합니다.
| 관점 | Markdown | 리치 HTML |
|---|---|---|
| 도표/레이아웃 | 이미지 붙이기만 함 | CSS로 자유롭게 표현 및 반응형 구현 |
| ... | 그대로 작동하는 화면으로 보여줄 수 있음 | |
| 공유 | 렌더러에 의존하여 깨짐 | URL을 열면 누구나 동일한 모양 |
| AI와의 궁합 | 문장 생성 중심 | 화면/도표를 한 파일로 생성 가능 |
주목해야 할 것은 마지막 줄입니다. AI에게 '이 기능의 목업을 만들어줘'라고 요청하면, Tailwind가 포함된 단일 HTML이 수십 초 만에 반환됩니다. 도식화 역시 마찬가지여서, 'SQS + Lambda의 비동기 처리를 그림으로 설명해줘'라고 하면 화살표나 박스를 CSS로 그린 설명 페이지가 나옵니다.
개조식 명세보다 작동하는 화면이나 그려진 도표가 리뷰와 합의 형성이 더 빠릅니다. 이것이 HTML로 남겨야 하는 가장 큰 동기입니다.
목업은 '단일 HTML'로 만들면 운영이 편하다
AI에게 목업을 만들게 할 때, 외부 파일로 나누지 않고 CSS와 JS를 인라인으로 포함한 단일 HTML을 기본으로 하면 이후의 운영이 매우 편리해집니다.
<!doctype html>
<html lang=
資料が増えると、入口ページ（リンク集）のメンテが面倒になります。モックを追加するたびに手で index を更新するのは、まず続きません。
ここで効くのが **ホスティングのビルドフェーズでの自動生成**。`amplify.yml` の build にスクリプトを1行足すだけです。
version: 1
frontend:
phases:
...
スクリプト側は、各モックの `<title>` を読んで一覧をカテゴリ別に組み立て、ポータルの**マーカーコメントの間だけ**を差し替えます。冪等なので何度実行しても同じ結果になります。
// <!-- MOCKS:START --> 〜 <!-- MOCKS:END --> の間を再生成
const block = ${START} ${sections.join(' ')} ${END}
const re = new RegExp(${START}[\s\S]*?${END})
...
これで **モックを push するだけで一覧が常に最新**になります。手動更新はゼロ。
### なぜ GitHub Actions の自動コミットにしなかったか
「push 時に一覧を再生成」と聞くと、GitHub Actions で再生成して**自動コミット**する方式を思い浮かべます。でも今回は採りませんでした。
| 方式 | 仕組み | 難点 |
|---|---|---|
| GitHub Actions | push → 再生成 → 自動コミット → 再 push | コミットループ防止・bot 権限が必要、二度 push |
| ビルドで生成（採用） | push → ホスティングのビルドで生成 → 配信 | コミットを汚さず・ループなし |
判断基準はシンプルで、「**生成物をリポに残したいか / 配信時だけ最新ならいいか**」です。配信が目的なら、ホスティングのビルドに寄せるほうが圧倒的に楽でした。
## 落とし穴と注意点
実際にやってみて気づいたことを3つ。
## まとめ
AI で成果物を量産できる時代だからこそ、「**伝わる形で残す**」価値が上がっています。今回の学びをチェックリストにすると、こうなります。
-
企画・設計の成果物は、Markdown より **リッチな HTML**で -
- モックは **単一 HTML**で作ると共有・運用が楽 -
- 社内資料は **Basic 認証付きホスティング**（Amplify など）に置く -
- 入口の一覧は **ビルドで自動生成**してメンテレスに -
- **公開境界**と**Markdown / HTML の使い分け**を意識する
AI が作ったものを、認証付きの URL でサクッと社内に見せる。
この導線を一度整えておくと、**企画のスピードがそのまま共有のスピード**になります。AI で「作る」のが速くなったぶん、「見せる」も同じ速度に揃えていきたいところです。
### Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기