Agentic Coding 시대의 Repo 부트스트래핑 가이드 Part 2: Go + Templ + HTMX To-Do 앱으로 직접 만들어 보기

# gotodo

A minimal SSR-based To-Do app. Go + Templ + HTMX + SQLite.
Single-user, local-first. No JS framework, no build step.

## Quick start

```bash
git clone https://github.com/example/gotodo
cd gotodo
make dev          # http://localhost:8080

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
git add AGENTS.md CLAUDE.md GEMINI.md

# ARCHITECTURE

## 시스템 다이어그램

```mermaid
flowchart LR
    Browser["Browser<br/>(HTMX)"] -- HTTP --> Server["Go HTTP Server<br/>(net/http)"]
    Server --> Feature["features/task<br/>handler+store+view"]
    Feature --> DB[("SQLite<br/>tasks.db")]
    style Browser fill:#87CEEB,color:#000000
    style Server fill:#90EE90,color:#000000
    style Feature fill:#FFD700,color:#000000
    style DB fill:#FFB6C1,color:#000000
```

## 도메인 모델

가장 중요한 엔티티는 `Task` 하나입니다.

```go
type Task struct {
    ID        int64
    Title     string    // 1..200 chars, trim
    Done      bool
    CreatedAt time.Time // UTC
}
```

제약사항:

- `Title` 은 trim 후 빈 문자열이면 400 응답.
- `Title` 길이는 200자 초과 시 400.
- `Done` 토글은 idempotent.

## HTTP 라우트

| Method | Path                  | 응답                          |
|--------|-----------------------|-------------------------------|
| GET    | `/`                   | 전체 페이지 (full page)        |
| POST   | `/tasks`              | 새 row partial (`<li>`)        |
| POST   | `/tasks/{id}/toggle`  | 갱신된 row partial             |
| DELETE | `/tasks/{id}`         | 빈 응답 (HTMX 가 row 제거)     |

HTMX 의 부분 응답 패턴(out-of-band swap)을 사용합니다. JSON 은 쓰지 않습니다.

## Templ 컴포넌트 구조

- `views.Layout(title)` — 전체 페이지 셸
- `views.TaskList(tasks)` — `<ul>` 컨테이너
- `views.TaskRow(t)` — 하나의 `<li>` (POST/toggle/delete 의 응답이 곧 이 컴포넌트)
- `views.NewTaskForm()` — 상단 입력 폼

핵심 원칙: **HTTP 핸들러는 한 컴포넌트만 렌더링** 한다. 페이지 한 덩어리를 통째로 반환하는 경로는 `GET /` 뿐.

## 의존성 흐름

```
cmd/server/main.go
  └─ internal/server.New(db)
       └─ features/task.NewHandler(store)
            └─ features/task.NewStore(db)
                 └─ internal/db.Open()
```

각 feature 패키지는 자기 `Store` 와 `Handler` 의 인터페이스를 자기 폴더 안에서 정의합니다.
다른 feature 의 internal 패키지를 import 하지 않습니다.

# DESIGN

## 1. Visual Theme & Atmosphere

**Terminal-minimal**. CLI 도구를 GUI 로 옮긴 듯한 인상.
이미지 없음, 그라데이션 없음, 애니메이션 최소. 정보 밀도와 빠른 조작감이 미관보다 우선.

## 2. Color Palette & Roles

| Token         | Hex       | Role                                |
|---------------|-----------|--------------------------------------|
| `--bg`        | `#0E1116` | 페이지 배경                          |
| `--surface`   | `#161B22` | 카드/리스트 항목 배경                |
| `--fg`        | `#E6EDF3` | 기본 텍스트                          |
| `--muted`     | `#8B949E` | 보조 텍스트, 완료된 task             |
| `--accent`    | `#3FB950` | 활성 상태, primary button            |
| `--danger`    | `#F85149` | 삭제, 에러 상태                      |
| `--border`    | `#30363D` | 1px 분할선                           |

다크 테마만 지원합니다. 라이트 테마는 v2 에서 검토 예정.

## 3. Typography Rules

전부 시스템 모노스페이스 스택. 별도 웹폰트를 다운로드하지 않습니다.

```css
font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo,
             Consolas, "Liberation Mono", monospace;
```

| Element     | Size | Weight | Line-height |
|-------------|------|--------|--------------|
| `<h1>`      | 24px | 600    | 1.3          |
| 본문        | 16px | 400    | 1.5          |
| Task title  | 16px | 400    | 1.4          |
| Hint/meta   | 13px | 400    | 1.4          |

## 4. Component Stylings

### Button — Primary (`+ Add`)
- bg: `--accent`, fg: `--bg`, padding: `8px 16px`, radius: `4px`
- Hover: opacity 0.9
- Disabled: opacity 0.4, cursor not-allowed

### Button — Danger (`✕`)
- bg: transparent, fg: `--danger`, radius: `4px`
- Hover: bg `rgba(248, 81, 73, 0.1)`

### Text Input
- bg: `--surface`, fg: `--fg`, border: 1px solid `--border`, radius: `4px`
- Focus: border-color `--accent`, outline 없음
- Placeholder: `--muted`

### Task Row (`<li>`)
- 가로 layout: `[checkbox] [title] ........ [delete]`
- padding: `12px 16px`, border-bottom: 1px solid `--border`
- 완료된 task: title 에 `text-decoration: line-through`, color `--muted`

## 5. Layout Principles

- **Spacing scale**: 4 / 8 / 12 / 16 / 24 / 32 (8px base, 4 와 12 만 예외)
- **Container**: max-width 640px, 가운데 정렬 (1인 앱은 좁은 폭이 자연스럽다)
- **Whitespace**: 항목 사이 0, 섹션 사이 24px. 빽빽함을 두려워하지 않는다.

## 6. Depth & Elevation

평면적 디자인을 유지합니다. shadow 는 다음 두 경우만 허용합니다.

- focus 가 들어간 input: `0 0 0 2px rgba(63, 185, 80, 0.3)`
- 에러 토스트(있다면): `0 4px 12px rgba(0, 0, 0, 0.4)`

## 7. Do's and Don'ts

**Do**
- 모노스페이스 폰트로 일관된 그리드 정렬을 유지한다.
- 상태 변화는 색으로 표현한다 (애니메이션 대신).
- 모든 상호작용은 키보드로도 가능해야 한다 (Tab/Enter/Space).

**Don't**
- 그라데이션, 이미지, 아이콘 폰트를 추가하지 않는다 (절대).
- 라이트 테마용 색을 임의로 도입하지 않는다 (ADR 로 제안 후).
- transition 시간을 200ms 보다 길게 두지 않는다.

## 8. Responsive Behavior

단일 컬럼 레이아웃이라 별도 breakpoint 가 거의 필요 없습니다.

- `< 480px`: container padding 16px → 8px
- 터치 타깃 최소 44×44px (delete 버튼 포함)

## 9. Agent Prompt Guide

새 UI 컴포넌트를 만들 때 에이전트에 던질 짧은 프롬프트 템플릿:

> Style this component using the tokens in `DESIGN.md`.
> Use `--accent` only for the primary action. Match the existing
> `TaskRow` density. Mono font, no images, no gradients.

색만 빨리 참조하고 싶을 때:

> Primary action → `--accent` (#3FB950). Destructive → `--danger` (#F85149).
> Surfaces → `--bg` / `--surface`. Text → `--fg` / `--muted`.

<!-- static/tokens.css : DESIGN.md 의 토큰을 그대로 옮긴 단일 파일 -->
:root {
  --bg: #0E1116;
  --surface: #161B22;
  --fg: #E6EDF3;
  --muted: #8B949E;
  --accent: #3FB950;
  --danger: #F85149;
  --border: #30363D;
}

// features/task/views.templ (발췌)
templ TaskRow(t Task) {
  <li class="task-row">
    <button class="btn-toggle"
            hx-post={ fmt.Sprintf("/tasks/%d/toggle", t.ID) }
            hx-target="closest li" hx-swap="outerHTML">
      if t.Done { ☑ } else { ☐ }
    </button>
    <span class={ "title", templ.KV("done", t.Done) }>{ t.Title }</span>
    <button class="btn-danger"
            hx-delete={ fmt.Sprintf("/tasks/%d", t.ID) }
            hx-target="closest li" hx-swap="delete">✕</button>
  </li>
}

# ADR-0001: HTMX over SPA

## Status

Accepted (2026-05-28)

## Context

`gotodo` 는 1인 로컬 사용을 가정한 학습 프로젝트입니다.
SPA 를 채택하면 다음이 따라옵니다.

- Node.js 빌드 파이프라인 (vite/esbuild)
- 클라이언트 라우팅
- JSON API 와 SSR 의 이원화

이 모든 비용이 학습 목적과 1인 사용 가정에 비추어 과합니다.

## Decision

다음을 채택합니다.

- 모든 페이지/부분 응답은 서버에서 HTML 로 렌더링한다 (templ).
- 인터랙션은 HTMX 의 attribute 만으로 작성한다 (`hx-post`, `hx-target`, `hx-swap`).
- 추가 클라이언트 JS 라이브러리는 금지한다.

## Consequences

### Positive
- 빌드 파이프라인이 `make build` 한 줄로 끝난다.
- 핸들러가 반환하는 응답이 곧 사용자에게 보이는 화면이라 디버깅이 쉽다.
- 에이전트가 "JSON 응답을 SPA 가 어떻게 그릴까" 를 추측할 필요가 없다.

### Negative
- 복잡한 클라이언트 상태가 필요한 화면(드래그앤드롭, 오프라인 큐 등)이 생기면 재검토 필요.
- HTMX 의 OOB swap 패턴에 익숙해지는 학습 비용.

## Alternatives considered

- **Next.js (App Router)** — 빌드 파이프라인 비용 과다.
- **Alpine.js + plain JSON API** — 응답 형태 이원화로 핸들러가 두 가지 모드를 가져야 함.
- **Vanilla JS + fetch** — 작성 비용은 낮지만 일관된 패턴을 강제하기 어려움.

# DEVELOPMENT

## 사전 요구사항

- Go 1.23+
- `templ` CLI (`go install github.com/a-h/templ/cmd/templ@latest`)
- `golangci-lint` (`brew install golangci-lint`)

## 자주 쓰는 명령어

```bash
make dev          # templ generate --watch + air (http://localhost:8080)
make test         # go test ./...
make lint         # golangci-lint run
make build        # CGO_DISABLED=1 go build -o bin/gotodo ./cmd/server
make migrate      # 누적된 migrations/*.sql 을 순서대로 적용
make clean        # bin/, *.db, templ 생성물 제거
```

## 환경변수

| 변수                | 기본값         | 설명                |
|---------------------|----------------|---------------------|
| `GOTODO_DB_PATH`    | `./gotodo.db`  | SQLite 파일 경로     |
| `GOTODO_LISTEN_ADDR`| `:8080`        | 서버 바인딩 주소     |

`.env.example` 를 복사해서 `.env` 를 만들면 `make dev` 가 자동으로 로드합니다.

## 테스트 작성 규칙

- 핸들러 테스트는 `httptest.NewServer` 로 실제 라우터에 붙입니다 (mock 금지).
- 스토어 테스트는 임시 SQLite 파일로 돌립니다 (`t.TempDir()`).
- 통합 테스트가 5\~10초 안에 끝나는 한, 모킹보다 실제 의존성을 선호합니다.

## 커밋 컨벤션

[Conventional Commits](https://www.conventionalcommits.org/).
PR 제목도 같은 규칙을 따릅니다. `commitlint` 가 CI 에서 검증합니다.

```
feat(task): add toggle endpoint
fix(store): handle empty title after trim
docs(adr): record HTMX-over-SPA decision
```

# SPEC-001: Task CRUD

## Background

`gotodo` 의 최소 기능 단위. 사용자가 할 일을 추가/완료/삭제할 수 있어야 한다.

## Goals

- 한 페이지에서 할 일을 입력하고 즉시 목록에 추가한다 (페이지 새로고침 없이).
- 각 항목을 클릭/체크하면 완료 상태가 토글된다.
- 삭제 버튼으로 항목을 제거한다.
- 모든 변경은 SQLite 에 즉시 반영된다.

## Non-goals

- 사용자 인증
- 마감일/우선순위
- 다중 사용자, 다중 디바이스 동기화

## Acceptance criteria

- [ ] `GET /` 가 현재 할 일 목록과 새 항목 입력 폼을 렌더링한다.
- [ ] `POST /tasks` 가 `title` 폼 값을 받아 새 항목을 저장하고, `TaskRow` 부분 응답을 반환한다.
- [ ] `title` 이 trim 후 빈 문자열이면 400 을 반환한다.
- [ ] `title` 길이가 200자 초과면 400 을 반환한다.
- [ ] `POST /tasks/{id}/toggle` 이 `Done` 을 뒤집고 갱신된 `TaskRow` 를 반환한다.
- [ ] `DELETE /tasks/{id}` 가 항목을 제거하고 빈 응답을 반환한다 (HTMX 가 DOM 에서 제거).
- [ ] 위 모든 동작에 대한 핸들러/스토어 테스트가 있다.

## Open questions

- 동일한 title 을 가진 항목을 허용할 것인가? → **허용**. 사용자가 일부러 둘 수 있음.
- 정렬 기준은? → `CreatedAt DESC` 로 시작. 나중에 spec 으로 분리 가능.