코딩 에이전트로 빌드하기

초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고 Mobile 로컬 설정을 완료하십시오. 코딩 에이전트는 AI 도구 — Cursor, Claude Code, Devin 또는 유사한 어시스턴트 — 로 프로젝트를 읽고 파일을 편집하고 명령을 실행합니다. 이 페이지의 모든 내용은 사용하는 어떤 도구에도 적용됩니다.

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

1. 리포지토리 루트의 .agents/skills/를 열고 태스크에 가장 가까운 스킬을 복사합니다 — add-a-mobile-screen이 좋은 첫 시도입니다.

2. 그것을 에이전트에 붙여넣고 변경 사항을 설명한 다음 한 줄을 추가합니다: 코드를 건드리기 전에 llms.txt, 다음 AGENTS.md, 다음 .ai/PROJECT_CONTEXT.md를 읽으십시오.

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

4. 게시, 스토어 제출, 유료 공급자 호출은 태스크 프롬프트의 일부가 절대 아닙니다. 명시적으로 승인하는 별도의 단계로 유지하십시오.

• 시작하기 전에
• 단말기 기본사항
• 모바일 로컬 설정

에이전트가 읽는 파일

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

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

포함된 스킬

.agents/skills/ 아래의 각 파일은 완전한 브리프입니다: 붙여넣거나 에이전트가 읽게 하면 키트의 규칙이 함께 전달됩니다 — 서버 우선 데이터, 번들에 비밀 없음, 오프라인은 네트워크 오류 폴백만.

붙여넣기 가능한 prompts/ 라이브러리는 Web 리포지토리에만 제공되고 이 체크아웃에는 대신 스킬이 있습니다. 무인 설정에는 agent-setup 가이드의 준비된 프롬프트를 사용하십시오.

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

• add-a-mobile-screen — 화면, 데이터 흐름, 오프라인 동작 추가 또는 변경
• adding-a-dependency — npm 종속성을 안전하게 추가, 업그레이드 또는 이동
• reviewing-a-pr — 정확성, 워크스페이스 격리, 비밀에 대한 diff 검토
• upgrading-from-upstream — 더 새로운 키트 릴리스를 앱으로 가져오기
• verify-changes — 인계 전에 올바른 검사를 선택하고 실행
• writing-unit-tests — Vitest로 새 로직 커버

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

에이전트는 세션 간에 메모리가 없습니다 — .ai/ 폴더가 메모리입니다. .ai/PROJECT_CONTEXT.md는 최근 변경 사항과 이유를 기록합니다. 그 옆의 .ai/apps/mobile/src/ideas/index.md와 같은 미러 문서는 코드만으로는 보이지 않는 apps/mobile/src/ideas/index.ts 뒤의 결정을 설명합니다.

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

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

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

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

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

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