> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 코딩 에이전트로 빌드하기

코딩 에이전트에게 작업 맡기기: 에이전트가 읽는 파일, 바로 붙여넣는 프롬프트 라이브러리, 무인 설정, 그리고 주도권을 유지하게 하는 리뷰.

## 초보자 워크스루

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료한 뒤, 이 저장소를 루트에서 편집기로 여세요. 코딩 에이전트는 프로젝트를 읽고, 파일을 편집하고, 명령을 실행하는 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. 게시, 배포, 유료 프로바이더 호출은 작업 프롬프트의 일부가 아닙니다. 명시적으로 승인하는 별도 단계로 유지하세요.

[시작하기 전에](https://supastack.dev/ko/docs/web/before-you-start.md)

[터미널 기본 사항](https://supastack.dev/ko/docs/web/terminal-basics.md)

[웹 로컬 설정](https://supastack.dev/ko/docs/web/ship-in-5-minutes.md)


## 에이전트가 읽는 파일

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

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

| 파일 | 에이전트에게 주는 것 |
|---|---|
| `llms.txt` | 저장소 진입 지도 — 읽을 가치가 있는 모든 문서와 보안 프로토콜이 읽는 순서대로 |
| `AGENTS.md` | 타협할 수 없는 경계: 더 승인하기 전까지 로컬 작업만, workspaceId 범위 지정, 서버 전용 시크릿 |
| `.ai/PROJECT_CONTEXT.md` | 세션을 가로지르는 메모리 — 최근에 무엇이 왜 바뀌었는지. 코드 변경 전에 읽음 |
| `.ai/` 미러 문서 | 중요한 파일 옆에 있는 대응하는 .ai/<path>.md 노트. 파일별 결정과 미해결 스레드를 기록 |
| `docs/agent-setup.md` | 무인 런북 — 설치, 마이그레이션, 배포 단계마다 검증 체크포인트가 뒤따름 |
| `prompts/` | 소유자가 가장 많이 요청하는 작업을 위한 붙여넣기용 작업 프롬프트 |
| `docs/agent-security.md` | 수용 체크리스트 — 인증, 워크스페이스 및 RLS 검사, 삭제된 로그, 배포 증거 |
| `.env.example` | 환경 설정의 완전한 목록 — 에이전트는 이 파일에 없는 변수명을 절대 만들지 않음 |


## 프롬프트 라이브러리

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

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

[에이전트가 설정을 실행하게 하기](https://supastack.dev/ko/docs/web/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 파일은 없습니다 — 그 앱들이 통신하는 백엔드가 웹 저장소에 있기 때문입니다.

[에이전트 주도 설정 진행하기](https://supastack.dev/ko/docs/web/agent-setup.md)


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

에이전트는 세션 사이의 메모리가 없습니다 — `.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를 돌려보내세요 — 실패한 검사를 지명하면 에이전트가 자기 작업을 가장 빨리 고칩니다. 혼자 시도해서는 안 되었던 일에 대해서는 한 번 명시적으로 말하세요. 그 경계는 나머지 세션 동안 유지됩니다.

[검증 게이트와 테스트 스위트](https://supastack.dev/ko/docs/web/testing.md)

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


설정을 계속하려면 [외부 계정 만들기](https://supastack.dev/ko/docs/web/external-accounts.md) 가이드를 읽어보세요.


## 다음

[외부 계정 만들기](https://supastack.dev/ko/docs/web/external-accounts.md)