로컬 우선 AI 디자인 데스크톱 앱을 정해진 제품 제약 안에서 고치기

## 지침 파일끼리 어긋나면 에이전트 가이드를 따르라 변경을 가하기 전에 이 파일을 읽어라. 리포지터리에 있는 다른 에이전트 지침 파일들은 현재 계획보다 뒤처져 있을 수 있다. 그것들이 이 파일과 어긋날 때는 이 파일이 우선한다. 비전 문서, 원칙 문서, 현재 릴리스 계획 같은 내부 설계 문서는 당신의 체크아웃에 존재한다면 유용한 추가 맥락이 된다. 내부 문서 디렉터리는 gitignore 처리되어 있으므로, 관리자는 계획·인수인계·조사 자료를 로컬에 보관하는 반면 공개 기여자에게는 그중 아무것도 없을 수 있다. - 관리자만 볼 수 있는 파일을 이유로 공개 기여자의 작업을 절대 막지 마라. - 공개 리뷰 코멘트에서 gitignore 처리된 문서 디렉터리 아래의 경로를 인용하지 마라. 단, 그 파일이 공개 체크아웃에도 존재하는 경우는 예외다. - 그 문서들이 없을 때는 이 파일과 공개 이슈 및 풀 리퀘스트, 그리고 README에 의존하라. ## 디자인 하나를 자기 워크스페이스를 가진 긴 세션으로 다루라 이 제품은 단일 프롬프트 생성기가 아니다. 각 작업 단위는 사용자의 머신에 있는 실제 워크스페이스에 의해 뒷받침되는 장시간 실행 에이전트 세션이며, 에이전트는 파일을 읽고 편집하고, 권한이 부여된 명령을 실행하고, 구조화된 질문을 하고, 산출물을 미리 보고, 조정 컨트롤을 노출하고, 설정된 모델이 지원할 때 이미지를 생성하고, 디자인 시스템 문서를 만들 수 있다. - 하나의 디자인이 하나의 워크스페이스를 소유한다. 봉인형/개방형의 구분은 없다. 워크스페이스 파일 시스템이 산출물과 에셋에 대한 진실의 원천이다. - 에이전트는 워크스페이스 안의 소스 파일을 편집하고, 미리보기 런타임은 그 소스들을 볼 수 있는 문서로 렌더링하며, 내보내기 도구는 렌더링된 문서 또는 소스 문서를 HTML, PDF, PPTX, ZIP, 마크다운 같은 표준 출력물로 변환한다. - 현재 형식에 대해 정식 소스 진입 파일 하나를 유지하고(예: JSX 컴포넌트 파일), 단독 실행형 HTML 파일은 내보내기용이나 레거시 워크스페이스 파일용으로 남겨 두라. - 검증된 코딩 에이전트 메커니즘을 빌려 오는 것은 의도된 것이다. 제품의 경계는, 도메인 특화 도구와 로컬 우선 워크스페이스 모델이 바로 당신이 그 위에 더하는 것이라는 점이다. ## 모델을 동봉하지 않고 사용자 키만 쓰는 등의 제약을 지켜라 이것들은 취향이 아니라 프로젝트의 약속이다. 편의를 위해 이것들을 맞바꾸지 마라. 1. 모델 런타임을 번들로 포함하지 않는다. 추론 엔진, 언어 인터프리터, 브라우저 바이너리, 모델 가중치를 설치 프로그램 안에 담아 배포하지 마라. 시스템에 설치된 것을 사용하거나, 사용자에게 보이는 동의를 받아 지연 다운로드하라. 2. 사용자 자신의 키만 사용한다(BYOK). 기본값으로 호스팅 계정, 프록시 API, 텔레메트리를 두지 않는다. 사용자 자격 증명은 사람이 읽을 수 있는 로컬 설정 파일에 머문다. 3. 로컬 우선 저장소. 세션은 추가 전용(append-only) 세션 파일과 실제 워크스페이스 파일로 존재한다. 레거시 임베디드 데이터베이스에 있는 기존 데이터는 마이그레이션할 수 있으나, 세션·채팅 기록·코멘트·스냅샷·디자인 파일을 위한 새 테이블을 거기에 추가하지 마라. 4. 모든 디자인은 워크스페이스를 가진다. 중요한 어떤 것도 세션 레코드 안에만 존재해서는 안 된다. 5. 배포되거나, 번들되거나, 링크되거나, 앱 코드에 임포트되거나, 사용자에게 배포되는 모든 것은 허용적(permissive) 라이선스여야 하며 프로젝트 라이선스와 호환되어야 한다. 그 범위 안에서는 카피레프트, 소스 공개형(source-available), 독점, 그리고 불분명한 서드파티 에셋을 거부하라. 워크플로 전용 CI 및 릴리스 도구는, 벤더링·번들링·링크되거나 제품 안으로 복사되지 않는 경우에 한해 카피레프트 라이선스를 사용할 수 있다. 그 이유를 문서화하고, 그 출력물은 일반적인 메타데이터나 매니페스트로 한정하라. 6. 무거운 기능은 지연 로딩하라. 내보내기 도구, 웹 캡처, 스캐폴드, 스킬, 참조 에셋, 이미지 생성은 애플리케이션 시작 시점이 아니라 필요할 때 로드되어야 한다. 7. 기반이 되는 에이전트 프레임워크의 기본 요소를 먼저 재사용하라. 프레임워크가 세션, 내장 도구, 셸 실행, 이벤트 스트리밍, 모델 레지스트리, 프로바이더 등록, 그리고 기능(capability) 데이터를 소유한다. 도메인 특화 필요성이 그렇지 않음을 입증하는 경우는 예외다. 8. 참조 데이터는 데이터이지 모델의 기억이 아니다. 브랜드와 스타일 값은 워크스페이스 디자인 문서, 사용자 파일, 공식 에셋, 또는 공개된 출처에서 가져와라. 브랜드 색상이나 사양을 기억에 의존해 지어내지 마라. 9. 변경은 호환 가능하고, 업그레이드 가능하며, 군더더기 없고, 우아해야 하며, 프로젝트의 상세 원칙 체크리스트가 존재할 때는 그것을 따라야 한다. ## 웹사이트를 만들 때 llms.txt 같은 AI용 파일도 준비하라 어떤 웹사이트, 프로젝트 홈페이지, 제품 페이지, 개인 사이트, 문서 사이트, 블로그, 공개 프로젝트 페이지를 구축하거나 갱신할 때, 사용자가 명시적으로 원하지 않는다고 밝히지 않는 한 AI 가시성을 기본 제공 범위에 포함하라. - 사이트, 저자 또는 조직, 핵심 페이지, 정식 프로젝트 또는 제품 설명, 그리고 기계가 읽을 수 있는 리소스로의 링크를 간결한 마크다운으로 개괄한 `/llms.txt` 파일을 추가하라. - 사이트에 더 완전한 AI 판독용 컨텍스트 파일을 정당화할 만큼 충분히 실질적인 공개 콘텐츠가 있을 때는 `/llms-full.txt` 파일을 추가하라. - `robots.txt`를 의도적으로 설정하라. AI 시스템이 공개 콘텐츠를 인용하거나 가져오는 데 도움이 되는 검색 및 검색 수집 크롤러는 허용하고, 학습용 크롤러는 별개의 정책 결정 사항으로 취급하라. - `sitemap.xml`을 유지하고 중요한 공개 페이지들을 빠짐없이 포함하는지 확인하라. 관련이 있을 때는 웹마스터 도구 제출을 언급하라. - 유용한 곳에는 사람, 조직, 웹사이트, 기사, 소프트웨어 애플리케이션, FAQ, 창작물 유형 등 적절한 JSON-LD 구조화 데이터를 추가하라. - 프로필, 프로젝트, 게시물, 문서, 릴리스, FAQ, 제품 정보 같은 중요한 개체에는 깔끔한 마크다운 또는 JSON 형태의 기계 판독용 엔드포인트를 선호하라. - 콘텐츠는 진실하고, 출처에 근거하며, 스팸성이 아니게 유지하라. 목표는 AI 시스템이 실제로 존재하는 콘텐츠를 정확하게 이해하고 인용하도록 돕는 것이지, 저품질의 채우기 글을 만들어 내는 것이 아니다. ## 모든 모델 호출과 도구는 공용 에이전트 프레임워크를 거치게 하라 - 직접 손으로 만든 대체물이 아니라, 공용 에이전트 프레임워크와 그 모델 추상화 계층 위에서 구축하라. - 읽기, 쓰기, 편집, 셸, grep, find, 목록 조회 작업에는 병행하는 별도 버전을 작성하지 말고 프레임워크의 내장 도구를 사용하라. - 모든 도구 호출은 프레임워크의 도구 호출 훅과 애플리케이션의 권한 UI를 통과하도록 통제하라. - 허용되는 입력 유형, 추론 지원 여부, 비용, 컨텍스트 윈도, 최대 출력 토큰 같은 모델 기능은 프레임워크의 모델 설명 필드에서 읽어라. 기능 표를 하드코딩하지 마라. - 커스텀 프로바이더는 프레임워크의 프로바이더 등록 API를 통해 등록하라. 병행하는 별도의 프로바이더 SDK 계층을 만들지 마라. - 모든 모델 호출은 프레임워크의 모델 추상화를 거친다. 애플리케이션 코드에서 벤더 SDK를 직접 임포트하지 마라. ## 세션은 추가 전용 파일에, 디자인은 워크스페이스에 두라 - 하나의 디자인이 하나의 세션이다. 세션 기록은 애플리케이션의 사용자 데이터 디렉터리 아래에 추가 전용 세션 파일로 존재한다. - 디자인 소스 파일, 생성된 마크업과 스타일, 에셋, 내보내기 결과물, 그리고 워크스페이스 수준의 에이전트 문서 및 디자인 문서는 애플리케이션 데이터베이스가 아니라 사용자 워크스페이스에 존재한다. - 워크스페이스 설정은 명시적인 스키마 버전 필드를 담은 버전 관리형 설정 파일에 존재한다. - 개인 로컬 설정 파일은 사용자별 파일이며 반드시 gitignore 상태를 유지해야 한다. - 레거시 임베디드 데이터베이스는 마이그레이션 대상 데이터이지 현재의 저장소 모델이 아니다. 새로운 기능 상태로 그것을 확장하지 마라. ## 내장 도구와 소수의 디자인 도구만 쓰라 도구 표면은 프레임워크의 내장 도구들에 더해 짧은 도메인 도구 목록으로 구성된다. - `ask(questions)` 는 구조화된 질문을 렌더링하고 사용자를 기다린다. - `scaffold(kind, path)` 는 엄선된 스타터를 워크스페이스로 복사한다. - `skill(name)` 은 매니페스트에서 스킬 텍스트를 지연 로딩한다. - `preview(path)` 는 산출물을 렌더링하고 콘솔 오류, 에셋 오류, DOM 개요, 지표, 그리고 비전 모델용 스크린샷을 반환한다. - `gen_image(prompt, path)` 는 기능과 프로바이더 설정이 허용할 때 생성된 이미지를 디스크에 쓴다. - `tweaks(blocks)` 는 여러 파일에 걸친 편집 가능한 컨트롤을 선언한다. - `todos(items)` 는 복잡한 턴에서 작업 상태를 보여 준다. - `done(path)` 는 미리보기 자체 점검 후 턴을 종료한다. 검증자 서브에이전트, 스니펫 캡처 도구, 커스텀 셸 도구, 커스텀 파일 목록 도구, 또는 에이전트가 직접 쓰는 작업 메모리를 다시 도입하지 마라. 계획이 바뀌는 경우는 예외다. ## 네 종류의 디자인 리소스를 섞지 말고 나눠 쓰라 디자인 문서는 공표된 사양을 따르며 입력이자 출력이 될 수 있다. 에이전트가 생성한 다중 화면 작업은 토큰이 드러날 때마다 그 문서를 갱신함으로써 시각적 일관성을 유지한다. 내장 참조 시스템은 저작자 표시, 출처, 라이선스 메타데이터, 그리고 "제휴 관계 없음" 문구를 반드시 담아야 하며, 내장 스킬은 표준 스킬 파일 형식을 사용한다. 스킬과 스캐폴드 매니페스트는 라이선스와 출처 메타데이터를 반드시 담아야 한다. 네 가지 리소스 종류는 서로 바꿔 쓸 수 없다. - 마크다운 스킬은 방법에 대한 규칙이다. 에이전트에게 어떻게 작업할지를 알려 줄 뿐, 워크스페이스로 파일을 복사하지 않는다. - 참조 디자인 시스템은 읽기 전용이며 이름으로 스킬처럼 로드된다. 프로젝트를 위해 그것들을 편집하지 마라. 당신이 채택한 선택 사항은 워크스페이스 디자인 문서로 옮겨 적어라. - 스캐폴드는 워크스페이스로 복사되는 구체적인 스타터 및 소스 에셋이다. 매니페스트가 그것들을 정확히 기술하는 한 어떤 텍스트 형식이어도 된다. - 디자인 스킬 스니펫은 가상 파일 시스템을 통해 노출되는 복사 가능한 컴포넌트 패턴이다. 이것들은 소스 스니펫이며, 방법 규칙도 아니고 브랜드에 대한 권위도 아니다. 워크스페이스 디자인 문서는 프로젝트별 바통이다. 일단 존재하게 되면 현재 디자인에 대해 권위를 가지며, 생성되는 작업물은 그것을 또 하나의 프리셋으로 취급하는 대신 보존하거나 복구해야 한다. ## 스타터를 제품 코드로 검토하고 확장자를 내용에 맞추라 - 스타터와 스캐폴드 에셋을 프롬프트 채우기용이 아니라 제품 코드로 취급하라. 프리셋을 변경하거나 추가하기 전에 매니페스트뿐 아니라 실제 파일 내용도 검토하라. - 소스 형식과 파일 확장자를 일치시켜라. 완전한 HTML 문서는 `.html` 파일에, 컴포넌트 스타터는 컴포넌트 확장자에, 스타일 스니펫은 `.css` 에 속한다. 복사 도구는 소스 확장자를 보존해야 하지만, 에셋 자체도 여전히 올바르게 이름 붙고 기술되어야 한다. - 내장 HTML 스타터는 자체 완결적이어야 하며 현재 런타임에서 미리보기가 가능해야 한다. 스캐폴드 에셋에 CDN이나 서드파티 런타임 스크립트를 추가하지 마라. 스타터에 런타임 동작이 필요하다면, 로컬의 순수 HTML·CSS·자바스크립트를 사용하거나, 라이선스 경로가 명확한 애플리케이션 제공 지연 로딩 의존성을 사용하라. - "덱 제목", "페이지 내용", "이것을 교체하세요", "첫 번째 항목" 같은 빈약한 자리표시 문구를 피하라. 중립적이고 실제로 쓸 만한 예시 콘텐츠를 사용하고, 명백한 교체 지점은 스타터가 선언한 조정(tweak) 기본값을 통해 노출하라. - 매니페스트 설명은 스타터가 어떤 형식인지 반드시 밝혀야 하며, 확장자에 민감한 에셋, 특히 에이전트가 자칫 잘못된 확장자로 복사할 수 있는 파일을 반드시 짚어 주어야 한다. - 스캐폴드 트리를 건드릴 때는 확장자와 내용의 불일치, 외부 네트워크 URL, 오래된 자리표시 문구, 매니페스트 드리프트를 점검하라. 변경이 복사 경로, 미리보기 분류, 또는 도구 동작에 영향을 준다면 초점이 맞춰진 스캐폴드 및 런타임 테스트를 추가하거나 갱신하라. ## 정해진 도구를 쓰고 버전은 락파일에서 확인하라 - 리포지터리 전체에 패키지 매니저는 하나만 쓴다. 두 번째 것을 절대 섞지 마라. - 대안을 새로 도입하지 말고, 리포지터리가 선택한 빌드 오케스트레이터, 단일 린트·포맷 도구, 단위 테스트 러너, 그리고 종단 간(E2E) 테스트 러너를 사용하라. - 타입스크립트는 strict 모드로, verbatim 모듈 구문과 번들러 해석 방식을 쓴다. `any` 는 금지다. - 커밋 메시지에는 Conventional Commits를, 버저닝에는 changeset 도구를 사용하라. 체인지로그를 손으로 편집하지 마라. 런타임 버전은 버전 파일과 engines 필드 양쪽 모두에 고정하라. - 정확한 패키지 버전은 매니페스트와 잠금 파일에 있다. 오래된 문서를 믿지 말고 그 파일들을 읽어라. - 프런트엔드 선택은 이미 확정되어 있다. 선택된 뷰 라이브러리와 빌드 도구, CSS 변수를 사용하는 유틸리티 CSS, 하나의 경량 상태 라이브러리, 공용 UI 패키지로 감싼 접근성 있는 헤드리스 프리미티브, 하나의 아이콘 세트, 폼 데이터를 쓰는 네이티브 폼, 그리고 애니메이션을 위한 CSS 트랜지션이다. 경쟁하는 상태·애니메이션·컴포넌트 라이브러리를 도입하지 마라. - 애플리케이션 크롬(chrome)은 반드시 공용 UI 패키지의 토큰을 사용해야 한다. 생성된 디자인 소스와 내보내기 결과물은 자체 시각 체계를 정의해도 된다. - 리포지터리는 애플리케이션 셸, 에이전트 코어, 프로바이더 통합, 미리보기 런타임, 공용 UI, 산출물 스키마, 내보내기 도구, 템플릿, 공용 타입을 별개의 패키지로 분리한다. 코드는 그 관심사를 소유한 패키지에 두라. ## 큰 작업은 계획 파일을 쓰고 수정 범위를 좁히라 - 사소하지 않은 아키텍처 작업이나 제품 작업의 경우, 비전·원칙·현재 계획 문서가 로컬에 존재한다면 그것들을 읽어라. 그렇지 않다면 이 파일과 공개 논의에 의존하라. - 도구 호출이 대략 다섯 번을 넘거나 파일이 세 개를 넘는 작업에는 지속되는 로컬 계획 파일을 작성하라. 작고 직접적인 수정에 계획 작업의 소모를 만들지 마라. - 병렬 작업이나 서로 무관한 기능 작업에는 별도의 워크트리를 사용하라. 서로 무관한 두 브랜치를 하나의 체크아웃에 섞지 마라. - 샌드박스, 인라인 코멘트, 조정 컨트롤, 내보내기 도구, 프레임워크 기능, 스캐폴드, 스킬, 참조 에셋을 건드리기 전에, 조사 대기열 파일이 로컬에 존재한다면 그것을 확인하라. - 편집 범위를 좁게 유지하고 지나가는 김에 하는 리팩터링을 피하라. - 배포되거나 런타임에 쓰이는 의존성을 추가하기 전에, 그 라이선스, 설치 크기, 대안, 그리고 피어 의존성이 될 수 있는지를 확인하라. 워크플로 전용 도구의 경우, 왜 번들되지 않는지와 그 출력물이 배포되는 산출물에 영향을 주는지를 문서화하라. - 기능 작업에는 단위 테스트 커버리지를 추가하거나 갱신하고, 마이그레이션·권한·도구 훅·공용 계약을 변경할 때는 테스트 범위를 넓혀라. - 실제 호출자가 둘이 되어 더 많은 것이 필요해지기 전까지는 레지스트리보다 매니페스트 더하기 스위치 로직을 선호하라. - 다음 관리자가 놀랄 만한 이유가 있는 곳에만 주석을 달아라. ## 명령을 네 단계 권한으로 나누고 막은 이유를 보여 주라 권한 모델은 하나이며, 등급이 단계적으로 올라간다. - 등급 0: 워크스페이스 로컬 읽기와 쓰기, 단순 파일 명령, 그리고 읽기 전용 버전 관리 명령은 중단 없이 실행될 수 있다. - 등급 1: 설치, 빌드 명령, 로컬이 아닌 네트워크 가져오기, 그리고 작업 디렉터리 바깥의 명령은 한 번 묻고, 그 뒤에는 허용 목록에 올릴 수 있다. - 등급 2: 게시, 푸시, 권한 상승, 그리고 그 밖의 파급 범위가 큰 명령은 매번 묻는다. - 등급 3: 파괴적인 시스템 명령, 내려받은 스크립트를 곧바로 셸로 파이프하는 것, 그리고 시스템 디렉터리에 대한 쓰기는 명시적인 재정의 없이는 차단된다. 차단된 도구 호출을 숨기지 마라. 명령, 경로, 등급, 그리고 차단된 이유를 보여 줘라. ## 벤더 SDK를 직접 가져오거나 동의 없는 추적을 넣지 말라 - 의존성 디렉터리, 빌드 산출물, 환경 파일, 생성된 릴리스 산출물, 또는 개인 로컬 파일을 버전 관리에 추가하는 것. - 애플리케이션 코드에서 모델 벤더 SDK를 임포트하거나, 벤더 SDK 수준에서 모델을 목(mock)으로 대체하는 테스트를 작성하는 것. 대신 코어나 프레임워크 경계에서 목으로 대체하라. - 명시적인 옵트인 경험 없이 추적, 분석, 계정 흐름, 클라우드 동기화, 또는 자동 업데이트를 추가하는 것. - 사용자 경로를 하드코딩하는 것. 플랫폼의 디렉터리 관례, 애플리케이션의 경로 API, 그리고 워크스페이스 루트를 존중하라. - 세션이나 디자인 데이터를 위해 레거시 데이터베이스에 기반한 새 기능 상태를 추가하는 것. - 워크스페이스 위에 더 무거운 그룹화 추상을 도입하는 것. 여러 세션이 하나의 워크스페이스를 공유할 수는 있으나, 사이드바는 세션을 나열한다. - 세션 분기, 실행 취소와 버전 롤백, 외부 도구 서버 지원, 또는 커뮤니티 스킬 설치를 노출하는 것. 계획이 바뀌는 경우는 예외다. - 메인 프로세스, 코어, 프로바이더, 내보내기 도구, 또는 공용 패키지에서 원시 콘솔 호출을 사용하는 것. 프로젝트 로거를 사용하라.