Codex로 무료 온라인 툴 사이트 만들기: AGENTS.md 하네스 적용부터 직접 따라 하기

먼저, 왜 Codex에 하네스를 적용했을까?

이번에 만들려는 것은 회원가입 없이 브라우저에서 바로 사용할 수 있는 무료 온라인 툴 사이트입니다. UUID 생성기, JSON Formatter, Base64, Timestamp Converter, QR Code Generator처럼 작은 도구를 하나씩 늘려 갈 계획입니다. 처음에는 “Codex에게 도구 하나씩 만들어 달라고 하면 되지 않을까?”라고 생각하기 쉽습니다.

그런데 도구가 늘어나면 기준도 함께 늘어납니다. 어떤 페이지는 오류 메시지가 영어이고, 어떤 페이지는 복사 버튼이 없을 수 있습니다. 어떤 기능은 입력값을 서버로 보내고, 어떤 기능은 브라우저 안에서 처리할 수도 있습니다. 이처럼 같은 사이트 안에서 규칙이 제각각이 되는 것을 막기 위해 하네스(harness)를 적용했습니다.

하네스는 별도 프로그램이 아닙니다. Codex가 프로젝트를 작업할 때 먼저 읽고 지켜야 할 규칙, 안전 원칙, 확인 방법, 완료 기준을 적어 둔 프로젝트의 작업 안내서입니다. 새 팀원에게 “우리는 이런 방식으로 일합니다”라고 알려 주는 짧은 온보딩 문서에 가깝습니다.

이 프로젝트에서는 그 중심 파일을 AGENTS.md로 정했습니다. 코드와 파일명은 영어로, 사용자가 보는 문구와 오류 메시지는 한국어로 작성합니다. 가능한 기능은 브라우저에서 처리하고, 사용자 입력을 불필요하게 서버에 보내거나 저장하지 않습니다. 작업을 마친 뒤에는 정상 입력뿐 아니라 빈 입력과 잘못된 입력도 확인하며, 실제로 실행하지 못한 검증은 성공했다고 말하지 않도록 했습니다.

다만 AGENTS.md에 모든 내용을 넣지는 않았습니다. 긴 서비스 설명, 기능 목록, SEO, UI 규칙, 앞으로의 일정까지 한 파일에 쌓으면 Codex도 사람도 필요한 내용을 찾기 어려워집니다. 그래서 항상 지킬 짧은 약속은 AGENTS.md에, 필요할 때 펼쳐 볼 자세한 설명은 docs 폴더에 나눴습니다. 이제부터는 이 구조를 그대로 복사해 프로젝트에 넣고, Codex와 실제 작업을 시작하면 됩니다.

먼저 결론: AGENTS.md는 짧아야 합니다

무료 온라인 툴 사이트는 시간이 갈수록 도구가 늘어납니다. UUID 생성기에서 시작해 JSON, Base64, QR, 이미지, PDF 도구까지 확장될 수 있습니다. 이때 가장 중요한 것은 새 기능을 추가해도 방식이 흐트러지지 않는 것입니다.

AGENTS.md에는 Codex가 항상 지켜야 하는 핵심 규칙만 둡니다. 서비스의 긴 설명, SEO 세부 규칙, 화면 스타일, 개발 계획은 docs/로 분리합니다.

쉽게 기억하기: AGENTS.md는 “항상 지킬 약속”, docs는 “필요할 때 찾아보는 설명서”입니다.

실전용 AGENTS.md 예시

아래 정도면 충분합니다. 프로젝트 최상위 폴더에 AGENTS.md라는 이름으로 저장하세요. 처음부터 수백 줄짜리 규칙집을 만들 필요는 없습니다.

# Project

이 프로젝트는 브라우저에서 사용할 수 있는 무료 온라인 툴 사이트다.
초기 도구는 UUID Generator, JSON Formatter, Base64,
Timestamp Converter, QR Code Generator다.

## Stack

- Next.js App Router
- TypeScript (strict)
- Tailwind CSS
- shadcn/ui
- npm

## Core Rules

- 코드, 파일명, 변수명은 영어로 작성한다.
- 사용자 화면 문구와 오류 메시지는 한국어로 작성한다.
- 특별한 이유 없이 any를 사용하지 않는다.
- Server Component를 기본으로 하고, 이벤트/브라우저 API가 필요할 때만 Client Component를 쓴다.
- 같은 코드를 반복하지 말고 공통 컴포넌트와 lib 함수로 분리한다.
- 기존 코드와 디자인 패턴을 먼저 확인한 뒤 수정한다.
- 새로운 라이브러리 설치 전 브라우저 기본 API 또는 기존 패키지로 가능한지 확인한다.

## Tool Rules

새 도구를 추가할 때는 다음을 함께 처리한다.

- 독립적인 /tools/[slug] 페이지
- 고유 metadata와 설명
- 입력, 결과, 복사, 초기화 UI
- 빈 입력과 잘못된 입력의 오류 처리
- src/data/tools.ts의 Tool Registry 등록
- 사용 방법, 예시, 관련 도구 링크

## Privacy and Security

- 가능한 기능은 브라우저에서 처리한다.
- 사용자 입력과 업로드 파일을 불필요하게 서버로 전송하거나 저장하지 않는다.
- 비밀값을 코드에 작성하거나 .env 파일을 Git에 포함하지 않는다.
- 사용자 입력은 검증하고, 검증되지 않은 HTML을 그대로 렌더링하지 않는다.

## Before Finish

- 변경한 기능을 정상/빈/잘못된 입력으로 확인한다.
- 가능한 검증 명령을 실행한다: npm run lint, npm run build
- 실행하지 못한 검증은 완료 보고에 이유와 함께 적는다.
- 실제로 확인하지 않은 결과를 성공이라고 말하지 않는다.

좋은 규칙의 기준: 자주 필요한가, 매번 판단하기 어려운가, 지키지 않으면 문제가 커지는가. 세 질문에 모두 “예”라면 AGENTS.md에 넣을 만합니다.

docs 문서는 무엇을 담아야 할까?

문서는 많을수록 좋은 것이 아니라, 찾기 쉬울수록 좋습니다. 초기에는 아래 다섯 개면 충분합니다.

문서	담을 내용	언제 읽나
`PROJECT.md`	서비스의 목적, 대상 사용자, 핵심 원칙, 초기 도구	프로젝트 방향을 정할 때
`ROADMAP.md`	Phase별 개발 순서와 우선순위	다음 기능을 고를 때
`TOOLS.md`	새 도구 페이지를 추가하는 체크리스트	도구 하나를 새로 만들 때
`SEO.md`	제목, 설명, FAQ, 내부 링크, 사이트맵 규칙	검색 노출을 다듬을 때
`UI.md`	색상, 여백, 버튼, 모바일 화면의 공통 원칙	화면 디자인을 바꿀 때

PROJECT.md의 가장 작은 시작 예시

# Project Overview

## 목표
회원가입 없이 브라우저에서 바로 쓸 수 있는 무료 온라인 툴을 제공한다.
가능한 기능은 사용자 기기 안에서 처리해 개인정보와 운영비를 줄인다.

## 대상 사용자
- 간단한 변환 도구가 필요한 일반 사용자
- JSON, UUID, Base64 같은 도구를 자주 쓰는 개발자

## 초기 범위
1. UUID Generator
2. JSON Formatter
3. Base64 Encoder / Decoder
4. Unix Timestamp Converter
5. QR Code Generator

TOOLS.md에 넣을 체크리스트

# New Tool Checklist

- [ ] slug와 도구 이름 결정
- [ ] src/app/tools/[slug]/page.tsx 생성
- [ ] Tool Registry 등록
- [ ] 고유한 title과 description 작성
- [ ] 입력, 실행, 결과, 복사, 초기화 기능 구현
- [ ] 빈 입력/잘못된 입력/큰 입력 확인
- [ ] 사용 방법과 예시 작성
- [ ] 관련 도구 링크 추가
- [ ] 모바일 화면과 키보드 사용 확인

ROADMAP.md 예시: 무엇을 어떤 순서로 만들지

로드맵은 “언젠가 만들 기능” 목록이 아니라 지금 무엇을 먼저 만들지 결정하는 문서입니다. 완료된 항목은 체크 표시로 남기고, 다음 단계는 작게 유지하세요.

# Roadmap

## Phase 1 — Foundation

- [ ] Next.js 프로젝트와 기본 디자인 설정
- [ ] Header, Footer, 홈 화면
- [ ] /tools 도구 목록과 카테고리 구조
- [ ] Tool Registry (src/data/tools.ts)
- [ ] 개인정보처리방침과 이용약관 페이지
- [ ] 기본 metadata, sitemap, robots 설정

## Phase 2 — First Tools

- [ ] UUID Generator
- [ ] JSON Formatter
- [ ] Base64 Encoder / Decoder
- [ ] Unix Timestamp Converter
- [ ] QR Code Generator

## Phase 3 — Quality

- [ ] 모바일 화면과 접근성 점검
- [ ] 도구 검색과 관련 도구 추천
- [ ] 오류 메시지와 빈 상태 개선
- [ ] 핵심 로직 테스트 추가
- [ ] 성능 및 SEO 점검

## Later — Expand Carefully

- [ ] Markdown Preview
- [ ] URL Encoder / Decoder
- [ ] Hash Generator
- [ ] 이미지 리사이즈

새 도구는 기존 5개 도구의 사용성과 오류 처리가 안정된 뒤 추가한다.

SEO.md 예시: 검색을 위한 최소 규칙

SEO는 키워드를 반복하는 작업이 아닙니다. 사용자가 실제로 찾는 문제를 해결하고, 각 도구의 용도를 명확히 설명하는 것이 기본입니다.

# SEO Guide

## Every Tool Page

- 도구마다 고유한 title과 description을 작성한다.
- 주소는 영문 소문자 slug를 사용한다. 예: /tools/json-formatter
- 페이지 상단에 H1 도구 이름과 한 줄 설명을 둔다.
- 사용 방법, 실제 예시, FAQ를 제공한다.
- 비슷한 도구 2~4개를 내부 링크로 연결한다.
- 기능이 실제로 없는 페이지는 만들지 않는다.

## Metadata Example

title: "JSON Formatter | 무료 JSON 정리 및 검증 도구"
description: "브라우저에서 JSON을 보기 좋게 정리하고 오류를 확인하세요. 입력 데이터는 서버에 저장되지 않습니다."

## Site-wide Checks

- 새 도구를 추가하면 Tool Registry와 sitemap에 반영한다.
- canonical URL과 Open Graph 정보를 확인한다.
- 같은 제목·설명을 여러 페이지에 복사하지 않는다.
- 검색엔진만을 위한 부자연스러운 키워드 나열을 하지 않는다.

UI.md 예시: 화면이 제각각이 되지 않게 하는 기준

UI 문서는 멋진 디자인보다 일관된 사용 경험을 지키는 데 도움이 됩니다. 색상이나 숫자는 프로젝트가 시작된 후 실제 디자인에 맞게 바꿔도 됩니다.

# UI Guide

## Principles

- 모바일 화면을 먼저 고려한다.
- 도구 페이지는 제목 → 설명 → 입력 → 실행 → 결과 순서를 유지한다.
- 주요 버튼은 한 화면에서 쉽게 찾을 수 있어야 한다.
- 실행, 복사, 초기화 버튼은 역할이 구분되게 표시한다.
- 긴 결과 텍스트와 JSON은 줄바꿈 또는 가로 스크롤로 화면을 깨지 않게 한다.

## Common Components

- Header: 로고, 도구 목록 이동, 검색(추후)
- Tool Page: 제목, 설명, 입력 영역, 결과 영역, 사용 방법, FAQ, 관련 도구
- Footer: 개인정보처리방침, 이용약관, 안내 문구

## Accessibility

- 모든 입력 요소에 label을 제공한다.
- 아이콘만 있는 버튼에는 aria-label을 제공한다.
- 키보드 포커스가 보이게 유지한다.
- 색상만으로 성공·오류 상태를 구분하지 않는다.
- 오류 메시지는 무엇을 어떻게 고쳐야 하는지 한국어로 설명한다.

## Responsive Checks

- 360px 너비에서도 가로 스크롤이 생기지 않는다.
- 버튼 텍스트가 잘리지 않는다.
- 터치하기 어려울 만큼 작은 버튼을 만들지 않는다.

초보자를 위한 Codex 사용 순서

처음부터 “사이트 전체를 만들어줘”라고 하기보다, 작은 단위로 맡기면 결과를 확인하고 고치기가 훨씬 쉽습니다.

개발 환경 준비
Node.js LTS와 Git을 설치하고, 빈 Next.js 프로젝트를 만듭니다.
문서부터 저장
이 글의 AGENTS.md와 docs/ 초안을 프로젝트에 넣습니다.
기초 화면 요청
홈, 헤더, 푸터, 전체 도구 목록, 공통 도구 레이아웃까지만 먼저 요청합니다.
도구를 하나씩 추가
가장 쉬운 UUID Generator로 구조를 검증한 뒤 JSON Formatter처럼 다음 도구를 추가합니다.
매번 직접 확인
정상 입력뿐 아니라 빈 입력, 잘못된 입력, 휴대폰 화면도 확인합니다.
배포는 마지막
기초 기능과 정책 페이지가 안정된 뒤 Vercel 같은 서비스에 배포합니다.

첫 번째 요청 예시

프로젝트 루트의 AGENTS.md와 docs/PROJECT.md를 먼저 읽어줘.
아직 새 도구는 만들지 말고, Next.js App Router 기준으로
홈 화면, 헤더, 푸터, /tools 목록 페이지, 공통 도구 페이지 레이아웃의
구현 계획을 짧게 제안해줘. 기존 파일이 있으면 먼저 확인하고,
의존성 추가가 필요하면 이유를 설명해줘.

UUID 생성기를 만들 때 요청 예시

AGENTS.md와 docs/TOOLS.md를 읽고 UUID Generator를 추가해줘.
/tools/uuid-generator 주소에서 동작해야 해.
UUID v4를 여러 개 생성하고, 개수 선택, 결과 복사, 초기화 기능을 제공해줘.
브라우저의 crypto.randomUUID를 우선 사용하고, 빈 상태와 오류 상태를 고려해줘.
Tool Registry, metadata, 사용 방법, 관련 도구 영역도 함께 갱신해줘.
작업 후 실행한 검증과 실행하지 못한 검증을 정확히 알려줘.

나머지 4개 도구를 개발할 때 사용할 프롬프트

아래 프롬프트는 UUID Generator와 공통 레이아웃이 이미 만들어진 뒤, 한 번에 하나씩 Codex에 전달하는 용도입니다. 이전 도구가 제대로 작동하는지 먼저 확인한 뒤 다음 도구로 넘어가세요.

2. JSON Formatter

AGENTS.md와 docs/TOOLS.md를 먼저 읽고, 기존 UUID Generator의 구조와 디자인을 확인해줘.

JSON Formatter를 /tools/json-formatter에 추가해줘.

요구사항:
- 사용자가 JSON 텍스트를 붙여 넣을 수 있는 큰 입력 영역을 제공한다.
- "정리하기" 버튼을 누르면 들여쓰기 2칸의 보기 좋은 JSON으로 결과를 보여준다.
- 유효하지 않은 JSON이면 페이지가 멈추지 않게 처리하고, 가능한 경우 오류 위치를 포함한 이해하기 쉬운 한국어 메시지를 보여준다.
- 결과 복사와 초기화 기능을 제공한다.
- 빈 입력, 잘못된 JSON, 중첩된 긴 JSON을 확인한다.
- 브라우저에서만 처리하며 입력 내용을 서버로 보내거나 저장하지 않는다.
- Tool Registry, 고유 metadata, 사용 방법, 예시, FAQ, 관련 도구 링크를 함께 갱신한다.

새 라이브러리 설치는 필요할 때만 하고 이유를 먼저 설명해줘.
작업 후 변경 파일, 직접 확인한 동작, 실행한 검증과 실행하지 못한 검증을 정확히 알려줘.

3. Base64 Encoder / Decoder

AGENTS.md와 docs/TOOLS.md를 먼저 읽고, 기존 도구 페이지의 공통 UI와 오류 처리 방식을 확인해줘.

Base64 Encoder / Decoder를 /tools/base64에 추가해줘.

요구사항:
- 텍스트 입력 영역과 결과 영역을 제공한다.
- "Base64 인코딩"과 "Base64 디코딩" 동작을 명확히 구분해 제공한다.
- 한글, 이모지 등 UTF-8 텍스트가 깨지지 않게 처리한다.
- 잘못된 Base64 입력은 페이지가 멈추지 않게 처리하고, 사용자가 고칠 수 있는 한국어 오류 메시지를 보여준다.
- 결과 복사와 초기화 기능을 제공한다.
- 입력 데이터는 브라우저 안에서만 처리하고 서버로 전송하거나 저장하지 않는다.
- 빈 입력, 한글 텍스트, 이모지 텍스트, 잘못된 Base64를 직접 확인한다.
- Tool Registry, 고유 metadata, 사용 방법, 예시, FAQ, 관련 도구 링크를 함께 갱신한다.

작업 후 기존 도구와 UI가 일관적인지 확인하고, 변경 파일과 검증 결과를 정확히 알려줘.

4. Unix Timestamp Converter

AGENTS.md와 docs/TOOLS.md를 먼저 읽고, 기존 도구의 컴포넌트와 스타일을 재사용할 수 있는지 확인해줘.

Unix Timestamp Converter를 /tools/timestamp-converter에 추가해줘.

요구사항:
- 현재 시간을 Unix timestamp(초)와 밀리초 단위로 보여주고, 복사할 수 있게 한다.
- 사용자가 Unix timestamp를 입력하면 읽기 쉬운 날짜와 시간으로 변환한다.
- 사용자가 날짜와 시간을 입력하면 Unix timestamp로 변환한다.
- 입력 단위가 초인지 밀리초인지 혼동하지 않도록 화면에서 명확히 안내한다.
- 현재 시간 기준과 변환 결과의 시간대 표기 방식을 일관되게 제공한다. 기본은 사용자의 로컬 시간대로 표시한다.
- 범위를 벗어나거나 올바르지 않은 숫자는 한국어 오류 메시지로 안내한다.
- 초기화, 결과 복사, 빈 입력과 잘못된 입력 처리를 제공한다.
- 모든 처리는 브라우저에서만 실행한다.
- Tool Registry, 고유 metadata, 사용 방법, 예시, FAQ, 관련 도구 링크를 함께 갱신한다.

정상적인 초 단위 값, 밀리초 값, 음수 timestamp, 잘못된 입력을 확인해줘.
작업 후 변경 파일과 검증 결과를 정확히 알려줘.

5. QR Code Generator

AGENTS.md와 docs/TOOLS.md를 먼저 읽고, 기존 프로젝트의 패키지와 디자인 패턴을 확인해줘.

QR Code Generator를 /tools/qr-code-generator에 추가해줘.

요구사항:
- URL 또는 일반 텍스트를 입력하면 QR 코드를 생성한다.
- 입력이 비어 있을 때는 생성하지 않고 이해하기 쉬운 한국어 안내를 보여준다.
- 생성된 QR 코드를 화면에서 확인하고 PNG 이미지로 다운로드할 수 있게 한다.
- 오류 정정 수준과 이미지 크기 같은 옵션은 UI를 복잡하게 만들지 않는 범위에서 제공한다. 첫 구현에서는 필수 기능을 우선한다.
- 외부 라이브러리가 필요하면 널리 사용되고 유지보수되는 가벼운 라이브러리를 선택하고, 설치 이유와 브라우저 처리 여부를 설명해줘.
- 입력값을 서버로 전송하거나 저장하지 않는다.
- 일반 URL, 한글 텍스트, 빈 입력, 긴 텍스트를 확인한다.
- Tool Registry, 고유 metadata, 사용 방법, 예시, FAQ, 관련 도구 링크를 함께 갱신한다.

작업 후 다운로드 기능을 직접 확인하고, 변경 파일, 추가한 패키지(있다면 이유 포함), 실행한 검증과 실행하지 못한 검증을 정확히 알려줘.

처음 5개 도구의 추천 순서

UUID Generator — 입력이 거의 없어 가장 빠르게 공통 화면을 검증할 수 있습니다.
JSON Formatter — 입력 검증, 오류 메시지, 복사 기능을 연습하기 좋습니다.
Base64 Encoder / Decoder — 양방향 변환 UI를 만들 수 있습니다.
Unix Timestamp Converter — 날짜와 시간대 처리의 기본을 익힐 수 있습니다.
QR Code Generator — 외부 라이브러리 검토와 이미지 다운로드 기능을 경험할 수 있습니다.

핵심은 도구 개수가 아닙니다. 첫 도구 하나가 빠르고, 이해하기 쉽고, 모바일에서도 안정적으로 동작하도록 만드는 것이 다음 100개 도구의 기준이 됩니다.

이 블로그 검색

해피 테크로그