Initial commit

docs/superpowers/specs/2026-06-09-global-config-design.md

@@ -0,0 +1,108 @@
+# SQLite + FastAPI + Vue 전역 설정 분리 설계
+
+## 목표
+
+프론트엔드가 백엔드 API 주소를 코드 내부 상수에 직접 고정하지 않고, `index.html`의 전역 설정 객체를 통해 읽도록 바꿔서 포트 변경 시 자바스크립트 로직을 수정하지 않아도 되게 만든다.
+
+## 배경
+
+현재 예제는 `frontend/src/main.js`에 `API_HOST`, `API_PORT`, `API_BASE_URL` 상수가 직접 선언되어 있다.
+
+이 구조는 이전보다 단순하지만, 포트를 바꿀 때 여전히 `main.js`를 수정해야 한다. 예제 사용성 관점에서는 HTML 설정만 바꾸고 Vue 로직은 그대로 두는 쪽이 더 이해하기 쉽다.
+
+## 범위
+
+이번 작업은 다음을 포함한다.
+
+- `frontend/index.html`에 전역 설정 객체 추가
+- `frontend/src/main.js`가 전역 설정 객체를 읽도록 변경
+- 설정이 없을 때 기본값 `127.0.0.1:8000` 사용
+- README에 설정 위치를 `index.html` 기준으로 설명
+
+이번 작업은 다음을 포함하지 않는다.
+
+- 별도 `config.js` 파일 추가
+- `.env` 기반 설정 시스템 도입
+- URL 쿼리 파라미터 기반 포트 주입
+- 백엔드 설정 시스템 변경
+
+## 구조
+
+### 1. HTML 전역 설정
+
+`frontend/index.html`에 아래 형태의 전역 객체를 둔다.
+
+```html
+<script>
+  window.APP_CONFIG = {
+    apiHost: 'http://127.0.0.1',
+    apiPort: '8000',
+  }
+</script>
+```
+
+이 값은 프론트엔드 애플리케이션이 시작되기 전에 정의되어야 한다.
+
+### 2. 프론트엔드 설정 읽기
+
+`frontend/src/main.js`는 `window.APP_CONFIG`를 읽어 아래 값을 만든다.
+
+- `apiHost`
+- `apiPort`
+- `API_BASE_URL`
+
+설정이 없거나 일부 속성이 빠져 있으면 기본값을 사용한다.
+
+예시 구조:
+
+```javascript
+const appConfig = window.APP_CONFIG ?? {}
+const apiHost = appConfig.apiHost || 'http://127.0.0.1'
+const apiPort = appConfig.apiPort || '8000'
+const API_BASE_URL = `${apiHost}:${apiPort}/api`
+```
+
+## 데이터 흐름
+
+1. 브라우저가 `index.html`을 먼저 읽는다.
+2. `window.APP_CONFIG`가 전역으로 설정된다.
+3. `main.js`가 이 값을 읽어 실제 API 주소를 조합한다.
+4. Vue 애플리케이션은 조합된 API 주소로 CRUD 요청을 보낸다.
+
+## 기본값 처리
+
+전역 설정 객체가 없더라도 예제가 깨지지 않도록 기본값을 유지한다.
+
+- 기본 호스트: `http://127.0.0.1`
+- 기본 포트: `8000`
+
+즉, 설정 객체는 선택 사항이지만 존재하면 우선 적용된다.
+
+## README 문서화 방식
+
+README에는 아래 내용을 포함한다.
+
+- 기본 실행 예시
+- `index.html`의 `window.APP_CONFIG` 위치 설명
+- 포트 충돌 시 `apiPort`를 어떻게 바꾸는지 설명
+- 프론트 정적 서버 포트는 여전히 실행 명령에서 따로 바꾼다는 점
+
+## 오류 처리
+
+- 전역 설정이 없으면 기본값으로 동작한다.
+- 전역 설정의 값이 잘못되어 연결에 실패하면 기존 fetch 에러 문구를 보여준다.
+- README에 백엔드 포트와 `apiPort`가 같아야 한다는 점을 분명히 적는다.
+
+## 검증 기준
+
+다음 조건을 만족하면 성공이다.
+
+- `main.js`를 수정하지 않고 `index.html`의 `apiPort` 값만 바꿔 다른 백엔드 포트로 연결할 수 있다.
+- 전역 설정이 없어도 기본값으로 기존 CRUD 기능이 유지된다.
+- README만 읽어도 설정 위치와 수정 방법을 이해할 수 있다.
+
+## 구현 원칙
+
+- 기존 CRUD 기능은 그대로 유지한다.
+- 설정 시스템은 예제 규모에 맞게 가장 단순한 수준으로 둔다.
+- 포트 변경 지점은 한 곳으로 모은다.

docs/superpowers/specs/2026-06-09-port-config-split-design.md

@@ -0,0 +1,118 @@
+# SQLite + FastAPI + Vue 포트 설정 분리 설계
+
+## 목표
+
+현재 CRUD 예제의 백엔드와 프론트 실행 포트를 문서와 코드에서 더 분리해, 로컬 포트 충돌이 있어도 최소 수정으로 다시 실행할 수 있게 만든다.
+
+## 배경
+
+기존 예제는 아래 주소를 기본값으로 사용한다.
+
+- 백엔드 API: `http://127.0.0.1:8000`
+- 프론트 정적 서버: `http://127.0.0.1:5173`
+
+실행 중 실제로 `8000`, `5173` 포트가 이미 사용 중이어서 새 서버를 같은 포트에 띄우지 못했다. 따라서 포트를 바꾸는 방법이 코드와 문서에 더 명확히 드러나야 한다.
+
+## 범위
+
+이번 작업은 다음을 포함한다.
+
+- 프론트엔드의 API 주소 상수 구조를 분리
+- 백엔드 포트 변경 방법을 README에 명시
+- 프론트 정적 서버 포트 변경 방법을 README에 명시
+- 기본 포트와 대체 포트 예시를 함께 제공
+
+이번 작업은 다음을 포함하지 않는다.
+
+- 별도 설정 파일 도입
+- `.env` 기반 환경변수 시스템 추가
+- 프론트 번들러 도입
+- 런타임 자동 포트 탐지
+
+## 접근 방식
+
+### 1. 프론트 상수 분리
+
+`frontend/src/main.js`의 API 주소를 하나의 긴 문자열 대신 아래 상수로 분리한다.
+
+- `API_HOST`
+- `API_PORT`
+- `API_BASE_URL`
+
+예시 구조:
+
+```javascript
+const API_HOST = 'http://127.0.0.1'
+const API_PORT = '8000'
+const API_BASE_URL = `${API_HOST}:${API_PORT}/api`
+```
+
+이렇게 하면 백엔드 포트를 `8001` 같은 값으로 바꿀 때 한 줄만 수정하면 된다.
+
+### 2. 백엔드 실행 포트는 명령에서 제어
+
+백엔드는 FastAPI 코드 내부에서 포트를 고정하지 않는다. 실행 포트는 `uvicorn` 명령의 `--port` 옵션으로 제어한다.
+
+기본 실행:
+
+```bash
+uvicorn backend.main:app --host 127.0.0.1 --port 8000
+```
+
+대체 실행:
+
+```bash
+uvicorn backend.main:app --host 127.0.0.1 --port 8001
+```
+
+### 3. 프론트 정적 서버 포트는 명령에서 제어
+
+프론트 정적 서버도 코드가 아니라 실행 명령에서 포트를 선택한다.
+
+기본 실행:
+
+```bash
+python3 -m http.server 5173 -d frontend
+```
+
+대체 실행:
+
+```bash
+python3 -m http.server 5174 -d frontend
+```
+
+## README 문서화 방식
+
+README에는 아래 내용을 포함한다.
+
+- 기본 포트 실행 예시
+- 포트 충돌 시 대체 실행 예시
+- 프론트에서 `API_PORT` 값을 어디서 바꾸는지 설명
+- 백엔드와 프론트 포트는 서로 독립적으로 바꿀 수 있다는 점
+
+## 데이터 흐름
+
+1. 사용자가 백엔드를 원하는 포트로 실행한다.
+2. 프론트는 `API_HOST`와 `API_PORT`를 조합해 API 주소를 만든다.
+3. 프론트 정적 서버는 별도 포트에서 독립적으로 제공된다.
+4. 포트 충돌 시 백엔드와 프론트 포트를 각각 따로 변경할 수 있다.
+
+## 오류 처리
+
+- 프론트가 잘못된 백엔드 포트를 가리키면 기존처럼 fetch 에러 문구를 보여준다.
+- README에 포트 불일치 점검 순서를 넣어 사용자가 원인을 쉽게 찾을 수 있게 한다.
+
+## 검증 기준
+
+다음 조건을 만족하면 성공이다.
+
+- 프론트 코드에서 백엔드 포트를 한 곳만 바꿔도 API 주소가 함께 변경된다.
+- README만 읽어도 기본 포트와 대체 포트 실행 방법을 이해할 수 있다.
+- 기존 CRUD 기능은 변경 없이 유지된다.
+- 포트 충돌 상황에서 사용자가 다음 행동을 바로 선택할 수 있다.
+
+## 구현 원칙
+
+- 기존 CRUD 구조를 유지한다.
+- 설정 분리를 위해 새 시스템을 과하게 도입하지 않는다.
+- 실행 문서는 실제 충돌 상황을 해결하는 데 바로 도움이 되도록 쓴다.

docs/superpowers/specs/2026-06-09-skill-docs-design.md

@@ -0,0 +1,190 @@
+# skillDesk 문서 확장 설계
+
+## 목표
+
+현재 프로젝트의 10개 스킬 문서를 원문에 더 가깝게 확장하고, 사용자가 바로 이해하고 검증할 수 있도록 루트 README와 TRAE 실사용 테스트 시나리오 문서를 추가한다.
+
+## 범위
+
+이번 작업은 다음 세 가지를 포함한다.
+
+1. `.trae/skills/*/SKILL.md` 10개 문서 확장
+2. 루트 `README.md` 신규 작성
+3. `docs/test-scenarios.md` 신규 작성
+
+이번 작업은 다음을 포함하지 않는다.
+
+- 실제 스킬 실행 엔진 개발
+- 자동 테스트 실행 스크립트 작성
+- 외부 설치 자동화
+- Git 커밋 자동 생성
+
+## 현재 상태
+
+- 루트에는 [skillText.md](file:///Users/woozooni/Documents/trae_projects/skillDesk/skillText.md) 가 있고, 10개 스킬 목록의 한국어 번역이 있다.
+- `.trae/skills/` 아래에 10개 스킬 디렉터리와 `SKILL.md`가 생성되어 있다.
+- 현재 스킬 문서는 핵심 요약형에 가깝고, 원문 세부 규칙과 절차 복원 수준은 낮다.
+- 루트 `README.md`는 아직 없다.
+- 테스트 시나리오 문서도 아직 없다.
+
+## 설계 방향
+
+### 1. 스킬 문서 확장
+
+각 `SKILL.md`는 현재의 짧은 요약형에서 벗어나, 원문에 더 가까운 아래 구조를 갖는다.
+
+- 언제 사용하는지
+- 반드시 지켜야 하는 규칙
+- 단계별 작업 흐름
+- 권장/비권장 행동
+- 결과물 기대치
+- 필요 시 예시 프롬프트 또는 운영 팁
+
+모든 스킬을 원문 그대로 기계 번역하는 방식은 피한다. 대신 다음 원칙을 따른다.
+
+- 원문 핵심 규칙, 체크리스트, 금지 사항은 최대한 보존한다.
+- 한국어 사용성과 현재 프로젝트 맥락을 고려해 불필요한 외부 의존 서술은 줄인다.
+- 지나치게 긴 원문은 구조화해서 읽기 쉽게 재편집한다.
+- frontmatter `description`은 짧고 명확하게 유지한다.
+
+### 2. README 구조
+
+루트 `README.md`는 프로젝트 안내문 역할을 하며 아래 내용을 포함한다.
+
+- 프로젝트 소개
+- 포함된 10개 스킬 목록
+- 디렉터리 구조 설명
+- TRAE에서 사용하는 방법
+- 추천 사용 흐름
+- 문서 확장 기준 설명
+- 테스트 시나리오 문서 위치 안내
+
+README는 "이 저장소가 무엇인지, 어떻게 써야 하는지"를 처음 보는 사람도 바로 이해할 수 있게 작성한다.
+
+### 3. 테스트 시나리오 문서
+
+`docs/test-scenarios.md`는 실제 TRAE에서 복붙 가능한 검증 시나리오 모음으로 작성한다.
+
+각 시나리오는 아래 형식을 따른다.
+
+- 시나리오 목적
+- 사전 조건
+- 입력 프롬프트
+- 기대 동작
+- 확인 포인트
+
+10개 스킬 각각 최소 1개 이상의 대표 시나리오를 둔다. 필요하면 공통 시나리오도 추가한다.
+
+## 정보 구조
+
+### 스킬 문서 일관성 규칙
+
+모든 `SKILL.md`는 아래 섹션 순서를 가능한 한 맞춘다.
+
+1. 개요
+2. 언제 사용할지
+3. 핵심 규칙
+4. 단계 또는 워크플로
+5. 금지 사항 또는 안티 패턴
+6. 기대 결과
+7. 예시 또는 운영 팁
+
+스킬마다 성격이 다르므로 완전히 동일한 틀을 강제하지는 않지만, 사용자 관점에서 탐색성이 유지되도록 한다.
+
+### README와 테스트 문서 연결
+
+- README에서 테스트 시나리오 문서를 직접 링크한다.
+- README에서 스킬별 문서 위치도 빠르게 찾을 수 있게 정리한다.
+- 테스트 문서에서는 각 스킬 파일명을 명시해 사용자가 대응 관계를 이해할 수 있게 한다.
+
+## 구현 단위
+
+### 단위 A: 기존 스킬 문서 확장
+
+대상 파일:
+
+- `.trae/skills/brainstorming/SKILL.md`
+- `.trae/skills/frontend-design/SKILL.md`
+- `.trae/skills/ui-ux-pro-max/SKILL.md`
+- `.trae/skills/systematic-debugging/SKILL.md`
+- `.trae/skills/writing-plans/SKILL.md`
+- `.trae/skills/find-skills/SKILL.md`
+- `.trae/skills/using-superpowers/SKILL.md`
+- `.trae/skills/karpathy-guidelines/SKILL.md`
+- `.trae/skills/webapp-testing/SKILL.md`
+- `.trae/skills/agent-browser/SKILL.md`
+
+접근 방식:
+
+- 이미 있는 한국어 문서를 기반으로 구조를 넓힌다.
+- 원문에서 확인한 사용 시점, 워크플로, 금지 사항을 최대한 반영한다.
+- 서로 중복되는 규칙은 표현은 달리하되 의미를 맞춘다.
+
+### 단위 B: README 작성
+
+대상 파일:
+
+- `README.md`
+
+접근 방식:
+
+- 저장소 소개에서 시작해 사용 흐름으로 내려가는 구조를 사용한다.
+- 표 또는 목록으로 10개 스킬을 빠르게 훑을 수 있게 한다.
+- 문서 탐색 링크를 충분히 제공한다.
+
+### 단위 C: 테스트 시나리오 작성
+
+대상 파일:
+
+- `docs/test-scenarios.md`
+
+접근 방식:
+
+- 각 스킬당 1개 이상 총 10개 이상의 대표 프롬프트를 작성한다.
+- 실제 TRAE 사용자가 바로 실행할 수 있는 형태로 구체화한다.
+- 기대 결과를 너무 추상적으로 쓰지 않고, 어떤 종류의 응답이 나와야 하는지 명시한다.
+
+## 품질 기준
+
+완료 판단 기준은 다음과 같다.
+
+- 10개 스킬 문서가 현재보다 명확히 더 상세해진다.
+- README만 읽어도 프로젝트 구조와 사용법을 이해할 수 있다.
+- 테스트 시나리오 문서만으로 실제 검증을 시작할 수 있다.
+- 문서 간 링크와 역할 분담이 자연스럽다.
+- Markdown 진단 오류가 없다.
+
+## 리스크와 대응
+
+### 리스크 1: 문서가 과도하게 길어짐
+
+대응:
+
+- 핵심 규칙은 유지하되, 반복 표현은 줄인다.
+- 표와 목록을 적극 사용한다.
+
+### 리스크 2: 원문 충실도와 한국어 가독성 충돌
+
+대응:
+
+- 규칙과 단계는 원문에 가깝게 유지한다.
+- 설명 문장은 한국어 사용성을 우선해 재구성한다.
+
+### 리스크 3: 테스트 시나리오가 추상적이 됨
+
+대응:
+
+- 실제 입력 프롬프트를 그대로 넣는다.
+- 기대 응답의 구조와 체크 포인트를 함께 적는다.
+
+## 검증 계획
+
+- 수정 후 각 Markdown 파일에 대해 진단을 확인한다.
+- README, 테스트 문서, 스킬 문서 간 링크와 명칭 일관성을 점검한다.
+- 시나리오가 실제 스킬 설명과 어긋나지 않는지 교차 검토한다.
+
+## 최종 산출물
+
+- 확장된 10개 `SKILL.md`
+- 루트 `README.md`
+- `docs/test-scenarios.md`

docs/superpowers/specs/2026-06-09-sqlite-fastapi-vue-crud-design.md

@@ -0,0 +1,192 @@
+# SQLite + FastAPI + Vue CRUD 예제 설계
+
+## 목표
+
+기존의 단일 `'hello world'` 조회 예제를 확장해, SQLite에 저장된 메시지를 Vue 화면에서 생성(Create), 조회(Read), 수정(Update), 삭제(Delete)할 수 있는 목록형 CRUD 예제로 만든다.
+
+## 범위
+
+이번 작업은 다음을 포함한다.
+
+- SQLite `messages` 테이블 유지
+- 메시지 목록 조회 API 추가
+- 메시지 생성 API 추가
+- 메시지 수정 API 추가
+- 메시지 삭제 API 추가
+- Vue 화면에서 목록형 CRUD UI 구현
+- 초기 데이터로 `hello world` 1건 유지
+- 실행 문서 업데이트
+
+이번 작업은 다음을 포함하지 않는다.
+
+- 인증/권한
+- 검색/정렬/페이지네이션
+- 다중 테이블 관계
+- 복잡한 폼 검증
+- 배포 설정
+
+## 구조
+
+기존 분리형 구조를 그대로 유지한다.
+
+```text
+skillDesk/
+├── backend/
+│   ├── init_db.py
+│   ├── main.py
+│   ├── requirements.txt
+│   └── app.db
+├── frontend/
+│   ├── index.html
+│   └── src/
+│       └── main.js
+└── README.md
+```
+
+## 데이터 모델
+
+테이블명: `messages`
+
+컬럼:
+
+- `id` INTEGER PRIMARY KEY AUTOINCREMENT
+- `content` TEXT NOT NULL
+
+메시지 단위는 매우 단순하게 유지한다. 별도 제목, 작성일, 상태 컬럼은 추가하지 않는다.
+
+## API 설계
+
+### 1. 목록 조회
+
+`GET /api/messages`
+
+응답 예시:
+
+```json
+[
+  { "id": 1, "content": "hello world" }
+]
+```
+
+### 2. 생성
+
+`POST /api/messages`
+
+요청 예시:
+
+```json
+{
+  "content": "new message"
+}
+```
+
+응답 예시:
+
+```json
+{
+  "id": 2,
+  "content": "new message"
+}
+```
+
+### 3. 수정
+
+`PUT /api/messages/{id}`
+
+요청 예시:
+
+```json
+{
+  "content": "updated message"
+}
+```
+
+응답 예시:
+
+```json
+{
+  "id": 1,
+  "content": "updated message"
+}
+```
+
+### 4. 삭제
+
+`DELETE /api/messages/{id}`
+
+응답 예시:
+
+```json
+{
+  "success": true
+}
+```
+
+## 백엔드 설계
+
+- FastAPI는 기존 CORS 설정을 유지한다.
+- sqlite3 표준 라이브러리를 사용한다.
+- 입력 모델은 최소한으로 `content` 문자열만 받는다.
+- 빈 문자열은 거부한다.
+- 존재하지 않는 id에 대한 수정/삭제는 404로 반환한다.
+
+## 프론트엔드 설계
+
+### 화면 구성
+
+- 상단 제목과 설명
+- 새 메시지 입력 폼
+- 메시지 목록 영역
+- 각 항목의 수정 / 삭제 버튼
+- 수정 모드일 때 인라인 입력창과 저장 / 취소 버튼
+- 로딩 / 에러 / 빈 목록 상태 표시
+
+### 사용자 흐름
+
+1. 페이지 진입 시 목록을 불러온다.
+2. 입력창에 값을 넣고 생성 버튼을 누르면 메시지가 추가된다.
+3. 각 항목의 수정 버튼을 누르면 해당 줄이 편집 모드로 바뀐다.
+4. 저장 시 수정 API를 호출하고 목록을 갱신한다.
+5. 삭제 시 삭제 API를 호출하고 목록을 갱신한다.
+
+### 상태
+
+다음 상태를 최소로 둔다.
+
+- 전체 목록
+- 새 메시지 입력값
+- 현재 편집 중인 메시지 id
+- 편집 중 입력값
+- 로딩 상태
+- 에러 상태
+
+## 데이터 흐름
+
+1. `init_db.py`가 DB를 만들고 `hello world`를 기본 데이터로 넣는다.
+2. Vue는 페이지 로드 시 `GET /api/messages`를 호출한다.
+3. 사용자가 생성/수정/삭제를 수행하면 해당 API를 호출한다.
+4. 요청 성공 후 목록을 다시 불러오거나 로컬 상태를 갱신한다.
+
+## 오류 처리
+
+- 빈 메시지 생성/수정은 프론트엔드와 백엔드 모두에서 막는다.
+- 없는 메시지 수정/삭제는 404로 처리한다.
+- API 실패 시 화면에 간단한 오류 문구를 표시한다.
+
+## 검증 기준
+
+다음 조건을 만족하면 성공이다.
+
+- 초기 화면에 `hello world`가 포함된 목록이 표시된다.
+- 새 메시지를 추가할 수 있다.
+- 기존 메시지를 수정할 수 있다.
+- 기존 메시지를 삭제할 수 있다.
+- 삭제 후 목록이 즉시 반영된다.
+- README 실행 방법이 최신 흐름에 맞게 정리된다.
+
+## 구현 원칙
+
+- 기존 예제 구조를 최대한 유지한다.
+- 불필요한 라이브러리는 추가하지 않는다.
+- CRUD 흐름이 한눈에 보이는 최소 UI를 만든다.
+- 과도한 추상화보다 이해하기 쉬운 코드를 우선한다.

docs/superpowers/specs/2026-06-09-sqlite-fastapi-vue-hello-world-design.md

@@ -0,0 +1,140 @@
+# SQLite + FastAPI + Vue Hello World 예제 설계
+
+## 목표
+
+SQLite 데이터베이스에 저장된 문자열 `'hello world'`를 Python FastAPI 백엔드가 읽고, Vue 프론트엔드가 API를 호출해 화면에 표시하는 최소 동작 예제를 만든다.
+
+## 범위
+
+이번 예제는 다음 범위를 포함한다.
+
+- SQLite DB 파일 생성
+- 메시지 테이블 생성과 샘플 데이터 삽입
+- FastAPI에서 SQLite 데이터를 읽는 API 구현
+- Vue에서 API를 호출해 화면에 문자열 출력
+- 실행 방법 문서화
+
+이번 예제는 다음 범위를 포함하지 않는다.
+
+- 사용자 입력 폼
+- CRUD 전체 기능
+- 인증/권한
+- 상태관리 라이브러리
+- 배포 구성
+
+## 구조
+
+예제는 프론트엔드와 백엔드를 분리한 최소 구조로 만든다.
+
+```text
+skillDesk/
+├── backend/
+│   ├── main.py
+│   ├── init_db.py
+│   ├── requirements.txt
+│   └── app.db
+├── frontend/
+│   ├── package.json
+│   ├── vite.config.js
+│   └── src/
+│       ├── App.vue
+│       └── main.js
+└── README.md
+```
+
+## 데이터 흐름
+
+1. `backend/init_db.py`가 SQLite 데이터베이스 파일을 만들고 `messages` 테이블을 생성한다.
+2. 초기 데이터로 `'hello world'` 한 건을 삽입한다.
+3. `backend/main.py`의 `GET /api/message` 엔드포인트가 SQLite에서 첫 메시지를 읽는다.
+4. Vue 앱이 페이지 로드 시 `/api/message`를 호출한다.
+5. 응답 JSON의 메시지를 화면에 렌더링한다.
+
+## 백엔드 설계
+
+### 기술 선택
+
+- Python
+- FastAPI
+- sqlite3 표준 라이브러리
+- uvicorn
+
+### 엔드포인트
+
+`GET /api/message`
+
+응답 예시:
+
+```json
+{
+  "message": "hello world"
+}
+```
+
+### DB 스키마
+
+테이블명: `messages`
+
+컬럼:
+
+- `id` INTEGER PRIMARY KEY AUTOINCREMENT
+- `content` TEXT NOT NULL
+
+### CORS
+
+개발 중 Vue dev server에서 FastAPI API를 호출할 수 있도록 최소 CORS 설정을 추가한다.
+
+## 프론트엔드 설계
+
+### 기술 선택
+
+- Vue 3
+- Vite
+
+### 동작
+
+- 앱이 마운트되면 FastAPI API를 호출한다.
+- 로딩 중에는 간단한 로딩 문구를 표시한다.
+- 성공하면 DB에서 받은 `'hello world'`를 표시한다.
+- 실패하면 간단한 에러 문구를 표시한다.
+
+### 화면 구성
+
+예제는 최소 화면만 구성한다.
+
+- 제목
+- API에서 받은 메시지 출력 영역
+- 로딩/에러 상태 문구
+
+## 실행 흐름
+
+1. Python 가상환경 생성 및 의존성 설치
+2. SQLite 초기화 스크립트 실행
+3. FastAPI 서버 실행
+4. Vue 의존성 설치
+5. Vue 개발 서버 실행
+6. 브라우저에서 메시지 표시 확인
+
+## 검증 기준
+
+다음 조건을 만족하면 예제가 성공이다.
+
+- SQLite DB 파일이 생성된다.
+- `messages` 테이블에 `'hello world'`가 저장된다.
+- `GET /api/message` 호출 시 JSON 응답이 반환된다.
+- Vue 화면에서 `'hello world'`가 보인다.
+- 백엔드와 프론트엔드 실행 방법이 README에 정리된다.
+
+## 오류 처리
+
+최소 예제이므로 복잡한 예외 처리 대신 아래 수준만 포함한다.
+
+- DB에 메시지가 없으면 기본 에러 응답 반환
+- 프론트엔드 fetch 실패 시 에러 문구 표시
+
+## 구현 원칙
+
+- 예제는 최대한 짧고 이해하기 쉬워야 한다.
+- 구조는 실제 앱 구조와 유사하게 분리한다.
+- 과도한 추상화는 하지 않는다.
+- 의존성은 최소화한다.