# 내 웹 프로젝트

> 안녕하세요, 처음 프론트엔드 개발을 하게 된 여러분. 환영해요!
>
> 이 폴더는 `npx create-remember-web`으로 만든 웹 프로젝트예요. 코딩을 몰라도 **코드 퀄리티를 지키면서 좋은 제품을 만들 수 있도록** 준비되어 있습니다. 만들고 싶은 걸 한국어로 말하면 Claude가 화면을 만들고, 여러분은 화면을 보면서 다듬으면 돼요. 잘 만들려는 부담은 내려놓아도 됩니다.

> **처음이시라면 [15분 따라 하기](docs/TUTORIAL.md)부터 해보세요.** 화면 하나를 만들고, 고치고, 되돌리는 것까지 한 번 겪어보면 나머지는 응용입니다. 아래 내용은 그다음에 필요할 때 찾아보는 참고서예요.

# 1. 시작하고 끝내기

**다시 켤 때**: 터미널을 열고 아래 두 줄을 입력해주세요.

```bash
cd my-project
claude
```

`my-project` 자리에는 만들 때 정한 폴더 이름을 넣어주세요.

사이트가 안 떠 있으면 Claude에게 "화면 보여줘"라고 하면 알아서 켜 줍니다.

**끝낼 때**: `Ctrl + C`를 두 번 누르면 사이트와 Claude가 함께 꺼져요.

**Claude 없이 사이트만 켤 때**: 프로젝트 폴더에서 아래를 입력하면 됩니다. `pnpm i`는 처음 한 번이나 설치가 필요하다는 안내가 나올 때만 하면 돼요.

```bash
pnpm i
pnpm dev
```

`pnpm dev`가 켜지면 브라우저에서 `localhost:3000`으로 사이트를 볼 수 있어요. 3000을 이미 다른 사이트가 쓰고 있으면 `localhost:3001`처럼 옆 포트로 열려요 — 터미널에 뜨는 주소를 보시면 됩니다.

> 다른 컴퓨터에서 처음부터 세팅하려면(Node·Claude Code 설치, 새 프로젝트 만들기) [보일러플레이트 저장소 안내](https://github.com/dramancompany/frontend-boilerplate)를 따라주세요.

# 2. 화면 만들기

대화창에 만들고 싶은 걸 한국어로 말하면 됩니다. 예를 들어:

> 지원자 목록을 보여주는 화면을 만들어줘. 이름·지원일·상태가 표로 나오면 좋겠어.

Claude가 화면을 만들고 스스로 검사한 뒤, 다 되면 브라우저로 열어서 보여줘요. 이 흐름의 반복입니다.

1. **말하기** — "○○ 화면 만들어줘"
2. **보기** — 다 만들면 Claude가 브라우저로 열어서 보여줘요.
3. **고치기** — "버튼 좀 더 크게", "표로 바꿔줘", "파란색을 회색으로"
4. **되돌리기** — 잘못됐으면 "아까 상태로 되돌려줘"
5. **올리기** — "배포해줘"라고 하면 연결된 레포지토리에 배포돼요.

**소요 시간**: 화면 하나에 보통 10～15분 정도 걸려요. 겉으로 조용해 보여도 품질 검사까지 함께 돌리고 있어서 그렇습니다. 기획이 크면 30～40분까지도 걸리는데, 작업을 작게 쪼개서 요청하면 빨라져요.

**요청 전에 한 가지 팁**: 처음부터 러프하게 "뭔가 만들어줘"라고 하는 것보다, 해야 할 일을 Jira 티켓이나 Confluence 기획서로 먼저 정리한 뒤 그 내용을 통째로 붙여넣어 요청하는 편이 훨씬 효율이 좋아요. 요구사항이 문서로 정리되어 있으면 Claude가 헤매지 않고, 결과도 의도에 가깝게 나옵니다.

## 이렇게 말해보세요

| 상황              | 이렇게 말하면 돼요                                          |
| ----------------- | ----------------------------------------------------------- |
| 기획서대로 만들기 | 기획서나 Jira 티켓 내용을 통째로 붙여넣고 "이대로 만들어줘" |
| 새 화면 만들기    | "○○ 화면 만들어줘"                                          |
| 결과 보기         | "화면 보여줘"                                               |
| 기능 추가         | "목록에서 이름을 누르면 상세가 열리게 해줘"                 |
| 표 만들기         | "이걸 정렬·검색되는 표로 보여줘"                            |
| 디자인 바꾸기     | "○○앱처럼 깔끔한 느낌으로", "전체적으로 더 밝게"            |
| 저장되게 하기     | "새로고침해도 남게 해줘"                                    |
| 실수 되돌리기     | "아까 상태로 되돌려줘"                                      |
| 문제 신고         | "에러 나", "화면이 안 떠"                                   |

git, 커밋, 배포, 코드, 폴더 구조는 몰라도 됩니다. 전부 Claude가 알아서 해요.

## 자동으로 지켜지는 것

여러분이 따로 신경 쓰지 않아도:

- 처음 정한 디자인이 화면마다 달라지지 않아요. "전체적으로 더 밝게" 한마디면 모든 화면에 한 번에 적용됩니다.
- AI가 대충 만든 느낌이 나는 화면은 자동으로 걸러집니다.
- 코드 검사가 항상 돌고 있어서, 나중에 개발자가 이어받아도 문제없는 상태로 유지돼요.
- 파일 정리는 팀 표준대로 자동으로 됩니다.
- 회사의 실제 데이터는 여러분 확인 없이 외부 서비스에 올리지 않아요.
- 이 검사들을 전부 통과해야 Claude가 "다 됐어요"라고 말합니다.

**다만 검사를 통과했다는 게 "좋은 화면"이라는 뜻은 아닙니다.** 기계는 코드의 형태를 보지 의도를 보지 못해요 — 버튼이 눌리는지는 알아도, 그 버튼이 눌러야 할 버튼인지는 모릅니다. 실제로 모든 검사를 통과한 화면에서 "저장에 실패하면 다시 시도할 방법이 사라진다" 같은 문제가 뒤늦게 발견된 적이 있습니다. 그래서 마지막에 사람 대신 심사하는 단계(코드 리뷰·화면 심사)를 따로 두었고, **그래도 마지막 판단은 화면을 보는 여러분 몫입니다.** 이상하면 이상하다고 말해주세요.

# 자주 묻는 질문

**Q. 화면이 안 보여요.**

Claude에게 "화면 보여줘"라고 말해주세요. 알아서 켜서 열어줍니다.

**Q. 너무 오래 걸리는 것 같아요.**

화면 하나에 10～15분은 정상이에요. 기획이 크면 30～40분까지 걸릴 수도 있어요. 작업을 조금씩 쪼개서 요청하면 더 빨라집니다.

**Q. 터미널을 실수로 닫았어요.**

터미널을 새로 열고 `cd my-project`(만들 때 정한 폴더 이름)를 입력한 뒤 `claude`를 실행해주세요.

**Q. `pnpm`을 못 찾는다고 나와요.**

터미널에 `npm install -g pnpm`을 한 번 입력하고 다시 시도해주세요. `pnpm install`이 실패하면 `corepack enable`을 한 번 실행한 뒤 다시 해보세요.

**Q. `claude` 명령이 없다고 나와요.**

터미널에 `curl -fsSL https://claude.ai/install.sh | bash`를 실행해주세요 (윈도우 PowerShell은 `irm https://claude.ai/install.ps1 | iex`).

**Q. 기획서 링크(Confluence·Jira)를 못 읽는다고 해요.**

이 프로젝트에는 외부 도구 연결(MCP)이 두 개 들어 있어요 — 화면을 자동으로 검사하는 도구와, 기획서·티켓을 읽는 도구입니다. 연결은 **폴더 단위**라, 다른 폴더에서 연결해 뒀어도 여기선 다시 켜야 할 수 있어요.

1. Claude를 처음 켤 때 `MCP servers found` 물음이 나오면 **Enter로 켜주세요.**
2. 이미 지나쳤다면 대화창에 `/mcp`를 입력해 목록을 보고, 연결이 끊긴 항목을 다시 연결합니다. 로그인 창이 뜨면 사내 계정으로 승인해주세요.
3. 그래도 안 되면 Claude를 껐다 켠 뒤(`Ctrl + C` 두 번 → `claude`) 다시 `/mcp`를 확인하세요.

급할 땐 **기획서 본문을 복사해서 그대로 붙여넣는 게 가장 빠릅니다.** 링크를 못 읽어도 내용만 있으면 똑같이 만들어요.

**Q. 에러가 났는데 무슨 말인지 모르겠어요.**

Claude에게 그대로 "에러 나", "무슨 뜻인지 쉽게 알려줘"라고 물어보세요. 스스로 고치고 결과만 알려줍니다.

그래도 막히면 이 프로젝트를 안내해준 분께 물어보세요. 어떤 요청을 했을 때 무엇이 안 됐는지만 알려주시면 됩니다.

---

<details>
<summary><b>개발자를 위한 메모 (안 열어봐도 됩니다)</b></summary>

### 스택

Vite + React 19 + React Router · TypeScript · Tailwind v4 + shadcn/ui · TanStack Query(+ Table) · React Hook Form + Zod · Zustand · overlay-kit · ky · orval · React Compiler.

### 직접 쓸 수 있는 명령어

```bash
pnpm dev            # 개발 서버 (localhost:3000, 점유 시 옆 포트로)
pnpm preview        # 최소관문 (타입 확인 + slop) — 핑퐁 사이클용 빠른 게이트
pnpm build          # 프로덕션 빌드
pnpm verify         # 전체 품질 게이트 (lint·typecheck·test·code-smell·slop·build)
pnpm lint           # oxlint (type-aware, 엄격)
pnpm format         # oxfmt 포맷
pnpm codegen        # orval로 API 클라이언트 생성 (spec.json 기준)
```

### 코드 품질 — 5층 방어

1. **oxlint** (`.oxlintrc.json`) — 최고 수위 정적 검사. `any`·수동 메모(React Compiler라 useCallback/useMemo/memo 금지)·`let`/`var` 금지·promise 안전·FSD 경계·Tailwind 토큰·불필요한 useEffect 등. `pnpm lint`는 경고도 실패(`--max-warnings 0`).
2. **code-smell** (`.claude/scripts/code-smell.sh`) — oxlint로 못 잡는 구조 신호(한 컴포넌트 boolean useState 2개+·Suspense/ErrorBoundary 짝 등). 메시지가 Claude가 읽고 고치는 언어로 되어 있음.
3. **Claude PostToolUse hook** (`.claude/hooks/post-edit-check.sh`) — Claude가 파일을 저장하는 즉시 그 파일을 검사해 위반을 바로 알려줌 (가장 빠른 피드백).
4. **husky pre-commit** — 커밋 전 lint·typecheck·code-smell을 강제 (나쁜 코드 커밋 차단).
5. **GitHub Actions** (`.github/workflows/`) — PR·push에서 `pnpm verify` + `gate:selftest` + gitleaks 비밀키 스캔. **표준 액션만 쓰므로 어느 레포에서든 그대로 동작합니다** — 사내 시크릿도, 조직 전용 워크플로도 필요 없어요.

코드 리뷰는 서버가 아니라 로컬에서 합니다 — 배포·푸시 직전에 `.claude/agents/fe-reviewer`(코드)와 `ui-critic`(화면)이 깨끗한 컨텍스트에서 판정합니다. 둘 다 게이트가 이미 잡는 것은 보고하지 않고, 판단이 필요한 것(배치·캐시 파급·데이터 안전)만 봅니다.

위 다섯은 전부 **코드가 나온 뒤에** 도는 검사입니다. 그 앞에 하나가 더 있어요:

0. **설계 단계 게이트** (`.claude/hooks/ux-contract-guard.sh`) — 새 화면의 첫 파일을 쓰기 전에, 설계 문서(`docs/features/<slug>.md`)에 UX 계약 5줄(register·되돌릴 수 없는 동작·빈 상태·로딩/실패·최소 폭)이 정해졌는지 막습니다. "어떻게 생겼나"가 아니라 "어떻게 행동하나"는 코드 뒤에 고치면 구조를 다시 짜야 해서, 앞으로 당겼습니다.

### 하네스가 스스로 강해지는 방식

- 교정받은 것·조용한 실패는 `.claude/wiki/incidents.md`에 술어형으로 쌓입니다. 색인(`.claude/wiki/index.md`)은 세션 시작에 자동으로 주입돼요.
- 같은 술어가 **2회 이상 재발**하면 `.claude/rules/gate-promotion.md`의 3판정으로 게이트나 rule로 승격시킵니다. 기계 판정이 가능하면 게이트로, 판단이 필요하면 rule 문장으로.
- 게이트를 새로 만들 땐 **위반/허용 픽스처 쌍**이 의무입니다 (`pnpm gate:selftest`). 게이트가 조용히 죽거나 오탐을 내면 셀프테스트가 잡아요.
- 예외는 사유를 반드시 적습니다: `code-smell-ok(<이름>): 사유`, knip `/** @public */`.

디자인 토큰·오탐 방지 등 세부는 프로젝트 안 `CLAUDE.md`와 `.claude/skills/`를 참고하세요. FSD 배치 원칙은 `.claude/skills/feature-sliced-design`(공식 v2.1) + `fsd-router`. 쿼리·목 데이터 자리는 `query-factory`(`entities/<domain>/api/`).

</details>