코딩 에이전트로 빌드하기

초보자 워크스루

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료한 뒤, 이 저장소를 루트에서 편집기로 여세요. 코딩 에이전트는 프로젝트를 읽고, 파일을 편집하고, 명령을 실행하는 AI 도구입니다 — Cursor, Claude Code, Devin 같은 어시스턴트. 이 페이지의 모든 내용은 어떤 도구를 쓰든 똑같이 적용됩니다.

빠른 용어: 프롬프트는 에이전트에 붙여넣는 지시 텍스트입니다. diff는 에이전트가 제안하는 파일 변경 목록입니다. 저장소 루트는 package.json이 들어 있는 최상위 폴더입니다 — 에이전트는 항상 거기서 시작해야 합니다.

1. 저장소 루트의 prompts/ 폴더를 열고 작업에 가장 가까운 프롬프트를 복사하세요. new-landing-page.md가 첫 시도로 좋습니다.

2. 에이전트에 붙여넣고 <placeholders>를 채우세요: 원하는 라우트, 페이지나 화면이 해야 할 일, 누가 사용할 수 있는지, 성공이 어떤 모습인지. 그리고 한 줄을 추가하세요: 코드를 건드리기 전에 llms.txt, AGENTS.md, .ai/PROJECT_CONTEXT.md를 순서대로 읽을 것.

3. 에이전트가 편집하기 전에 변경할 파일과 실행할 검사를 나열하게 하세요. 끝나면 diff를 리뷰하세요 — 제품에 대한 실제 변경을 승인하는 것입니다.

4. 게시, 배포, 유료 프로바이더 호출은 작업 프롬프트의 일부가 아닙니다. 명시적으로 승인하는 별도 단계로 유지하세요.

• 시작하기 전에
• 터미널 기본 사항
• 웹 로컬 설정

에이전트가 읽는 파일

저장소에는 사람뿐 아니라 에이전트를 위해 쓰인 작은 파일 묶음이 들어 있습니다. 이 컨텍스트를 직접 붙여넣을 필요는 없습니다 — 에이전트를 llms.txt로 향하게 하면 나머지는 스스로 읽습니다.

읽는 순서가 중요합니다: llms.txt는 지도이고, AGENTS.md는 경계를 정하며, .ai/PROJECT_CONTEXT.md는 이전 세션에서 배운 내용을 담고 있습니다. 경계를 건너뛰는 에이전트는 출시할 수 없는 코드를 만듭니다.

프롬프트 라이브러리

prompts/README.md가 인덱스입니다. 각 파일은 완성된 브리프입니다: 붙여넣고 <placeholders>를 채우면 키트의 규칙 — 하드코딩된 색상보다 디자인 토큰, 직접 만든 패턴보다 키트 블록 — 이 함께 전달됩니다.

처음부터 실행까지 가는 경로에는 대신 prompts/agent-setup.md를 붙여넣으세요 — 다음에 설명하는 무인 설정을 구동합니다.

• 에이전트가 설정을 실행하게 하기

• agent-setup.md — 에이전트로 키트를 세우고 배포하기
• pick-a-style.md — 제품 전체에 디자인 스타일 적용하기
• new-landing-page.md — 키트 블록으로 마케팅 페이지 조립하기
• new-app-screen.md — 워크스페이스 앱 셸 안에 화면 추가하기
• restyle-product.md — 기존 페이지를 키트 토큰으로 리테마하기
• ui-audit.md — 라우트에 시각 및 접근성 감사 실행하기

에이전트에게 설치와 배포 맡기기

키트는 대부분 스스로 설정될 수 있습니다. prompts/agent-setup.md를 붙여넣으면 에이전트가 docs/agent-setup.md — 함께 제공되는 런북 — 를 단계별로 실행합니다: 사전 점검, 환경 파일, 설치, 데이터베이스 시작, 마이그레이션, 앱 시작, 그리고 선택적으로 VPS 배포. 각 단계 후에는 그 단계의 검증 체크포인트를 실행하고 주장이 아닌 실제 출력을 보고합니다.

두 개의 헬퍼가 이를 안전하게 지킵니다. scripts/setup-env.mjs는 .env.example에서 env 파일을 부트스트랩합니다: 없는 파일만 만들고, 없거나 자리 표시자인 시크릿만 생성하며, --check 모드는 쓰기 없이 검증합니다. docker-compose.dev.yml은 완전히 컨테이너화된 개발 환경 — Postgres와 Node 22 개발 컨테이너 — 이므로 에이전트는 컴퓨터에 설치된 Node.js가 필요하지 않습니다.

여기서는 어떤 저장소를 받았는지가 중요합니다. 웹 저장소와 All Platforms 모노레포에는 런북, compose 파일, scripts/setup-env.mjs, prompts/가 들어 있습니다. 독립 모바일·데스크톱 저장소에는 범위가 지정된 llms.txt, AGENTS.md, .ai/ 미러 문서, docs/agent-security.md를 포함한 선별된 문서가 들어 있지만 설정 런북이나 compose 파일은 없습니다 — 그 앱들이 통신하는 백엔드가 웹 저장소에 있기 때문입니다.

• 에이전트 주도 설정 진행하기

에이전트가 세션 사이에서 기억하는 방법

에이전트는 세션 사이의 메모리가 없습니다 — .ai/ 폴더가 그 메모리입니다. .ai/PROJECT_CONTEXT.md는 최근에 무엇이 왜 바뀌었는지 기록합니다. 그 옆에는 .ai/apps/web/src/reports.md 같은 미러 문서가 apps/web/src/reports.ts 뒤에 있는, 코드만으로는 보이지 않는 결정을 설명합니다.

계약은 단순합니다: 파일을 편집하기 전에 그 미러를 읽고, 변경이 반영되면 미러를 업데이트합니다. Open Threads 항목은 끝나지 않은 작업을 기록해 다음 세션이 처음부터가 아니라 이어서 할 수 있게 합니다. 오래된 미러는 없는 것보다 나쁩니다 — 에이전트의 diff를 리뷰할 때 변경된 파일들의 미러가 코드와 함께 움직였는지 확인하세요.

실행 중인 앱 자체의 에이전트 표면

배포한 제품도 에이전트에 응답합니다 — 이 엔드포인트들은 저장소뿐 아니라 실행 중인 앱에 존재합니다.

• GET /llms.txt — 앱이 자체 llmstxt.org 인덱스를 제공합니다: 가이드, 공개 페이지, 공개 엔드포인트를 절대 URL로.
• POST /api/mcp — 앱의 도구를 노출하는 스테이트리스 MCP 엔드포인트. sk_ API 키를 베어러 토큰으로만 받습니다 — 브라우저 쿠키 세션은 적용되지 않습니다. Settings → Developers에서 키를 만드세요.
• GET /api/v1/openapi — 공개 REST API의 OpenAPI 명세. 클라이언트 생성기와 에이전트 도구용입니다.
• GET /api/health — 로드 밸런서와 가동 시간 검사가 호출하는 활성·의존성 프로브. 프로바이더 구성 종류를 보고하고 시크릿은 절대 반환하지 않습니다.
• /status — 각 서브시스템의 상태를 보고하는 사람이 읽을 수 있는 페이지.

에이전트의 작업을 정직하게 리뷰하기

완료된 작업은 요약이 아니라 증거입니다. 에이전트의 작업을 채택하기 전에 docs/agent-security.md가 배포를 검사하는 것과 같은 방식으로 확인하세요:

무언가 잘못되면 diff를 돌려보내세요 — 실패한 검사를 지명하면 에이전트가 자기 작업을 가장 빨리 고칩니다. 혼자 시도해서는 안 되었던 일에 대해서는 한 번 명시적으로 말하세요. 그 경계는 나머지 세션 동안 유지됩니다.

• 검증 게이트와 테스트 스위트

• 주장하는 테스트를 실행했는지 — 결론이 아니라 명령과 그 출력을 요구하세요.
• 시크릿이 서버 전용으로 유지됐는지 — 새로운 것에 NEXT_PUBLIC_ 또는 EXPO_PUBLIC_ 접두사가 없고, 키가 리포트나 커밋에 출력되지 않았는지.
• 모든 사용자 소유 읽기·쓰기가 workspaceId로 범위 지정된 채인지 — 어떤 쿼리도 브라우저가 보낸 id를 신뢰하지 않는지.
• 변경된 각 파일의 .ai/ 미러가 코드와 함께 움직였는지.
• 게시, 배포, 유료 프로바이더 호출이 승인된 별도 단계로 유지됐는지 — 에이전트가 스스로 머지, 푸시, 배포하지 않았는지.
• 한 단계가 두 번 실패하면 임기응변으로 우회하지 않고 멈춰 실패한 명령을 보고했는지.