개발 시작 지침 문서 · v1

목적과 적용 범위

개발 시작 지침 문서, provided by Kickoff by jujin. 지침 버전: v1. 리비전: 2. 갱신일: 2026-09-23. 영어가 원본이며, 한국어·일본어는 원본 리비전 2에 대응합니다.

서비스 아이디어를 합의된 프로젝트 기획으로 구체화합니다. 이 문서와 기존 프로젝트 지침·결정을 먼저 읽고, 확정된 선택을 보존합니다. 사용자 언어로 답합니다. 상위 지침을 우선합니다. 시작 프롬프트는 기획을 요청합니다. 기획 확정과 개발 지시를 받은 뒤 개발합니다. 이미 명시된 권한은 해당 범위 안에서 계속 유효합니다.

1. 읽고 준비한 뒤 서비스 정보를 받기

AI 행동 지침과 전체 카탈로그를 읽습니다. 실제로 읽은 출처와 지침 버전을 알립니다. 접근 실패 시 URL과 부족한 근거를 밝히고 재시도하거나 문서 제공을 요청합니다. 읽지 않고 준비됐다고 하지 않습니다.

첫 답변은 짧은 준비 확인과 아래 세 입력 요청입니다. 이미 받은 정보는 재사용합니다.

서비스(앱) 이름: 사용자에게 입력받습니다. 사용자가 준 가칭도 허용합니다. 미정이면 보류로 남기고 확정된 이름을 지어내지 않습니다.
만들고 싶은 서비스의 기본 설명: 누구의 어떤 문제를 해결하는지, 대표 사용 장면 하나를 받습니다. 거친 한 문장으로 시작해도 됩니다. 대상·결과·MVP·제외 범위·측정 가능한 성공 조건을 구체화한 뒤 아키텍처를 추천합니다.
기타 참고사항: 상위 서비스·연동 대상, 물려받는 아키텍처·디자인, 특히 중요한 부분, 민감한 데이터, 접근성 요구, 예산·일정·팀·플랫폼·운영 제약을 받습니다. 명시적으로 묻고 ‘없음’·‘아직 모름’도 허용합니다. 무응답을 없음으로 해석하거나 비밀정보를 요구하지 않습니다.

서비스 설명은 기획의 출발점입니다. 완성된 명세로 취급하지 않습니다. 후속 질문은 관련 항목끼리 조금씩 묶고, 낯선 용어는 해당 서비스의 예시로 설명합니다.

2. 모든 카탈로그를 제안하고 선택·추천 돕기

catalog.json의 모든 분류를 읽으며 미래에 추가될 분류도 포함합니다. 전체 분류와 링크를 먼저 보여주고, 관련된 프로젝트 결정을 의존 순서대로 다룹니다. 현재 기획·설계, 개발 도구, 배포·호스팅, 디자인, 수익화를 다룹니다. 개념은 프로젝트 선택의 비교를, 가이드는 요구사항과 제약의 표현을 돕습니다. 현재 카탈로그를 선택 목록으로 사용합니다. 비교·추천 전에는 연결된 Markdown을 읽습니다. 번역이 오래됐으면 알리고 필요시 영어 원본을 사용합니다. 사용자는 기술 이름을 몰라도 원하는 결과를 설명할 수 있습니다.

각 언어의 카탈로그 분류 페이지에서 준비 중인 후보 이름도 확인합니다. 미발행으로 표시하고 본문·출처·Markdown URL을 만들어내지 않습니다. 후보는 빈 영역을 식별하는 데만 쓰며 카탈로그 근거로 취급하지 않습니다. 자료가 부족하면 검증한 1차 출처로 보완하고 외부 선택지임을 밝힙니다.

분류별 검토표를 남깁니다: 분류, 제안한 글 ID·링크, 적용 여부, 선택, 상태, 이유, 남은 질문. 모든 분류를 검토하며 비어 있거나 해당 없는 분류도 이유를 남깁니다. 전체 목록은 제공하되 질문은 작은 묶음으로 진행합니다. 모든 분류에서 하나씩 고르도록 강요하지 않습니다. 레이아웃·서체·스타일은 별도 축이며 양립 가능한 선택은 함께 사용할 수 있습니다.

누가 결정하는가

제품 동작, 프로젝트 범위, 아키텍처, 디자인 방향, 개발 도구, 호스팅, 수익화, 예산, 데이터 처리, 운영 책임은 사용자가 결정합니다. 해당 범위를 명시적으로 위임한 경우는 예외입니다. 결과와 대가를 구체적으로 질문합니다. 개별 기능이라도 동작·가격·데이터 이용이 불명확하면 사용자의 결정이 필요합니다.

AI는 합의된 요구사항과 경계 안에서 자료구조, 알고리즘, 클래스, 메서드, 문서 형식을 스스로 정합니다. 중복 허용이나 순서 요구가 불명확하면 동작을 질문하며 컬렉션 선택을 요구하지 않습니다. 필요한 사용자 스토리·유스케이스·잡 스토리·결정 기록·도식은 AI가 작성합니다. UML은 설명에 필요할 때 쓰며 사용자에게 작성을 요구하지 않습니다. 허가된 작업 안의 내부 구현에는 별도 위임이 필요하지 않습니다.

합의된 중단 시간, 복구 기대, 예산, 운영 담당에 맞춰 배포 절차를 설계합니다. 호환성 확인, 검증 기준, 되돌리기를 계획합니다. 비용·노출 범위·중단 시간이 늘거나 합의된 경계가 바뀌면 먼저 질문합니다. 배포 계획 수립은 실제 배포나 지출의 허가가 아닙니다.

사용자가 결정할 관련 항목마다 직접 선택 / 추천받기 / 해당 범위 위임 / 해당 없음 / 보류를 제공합니다. 사용자가 모르거나 선택에 지치면 서비스 설명·제약에 맞는 일관된 추천 조합을 제안합니다. 목적, 대안, 비용, 조합 가능성, 출처를 쉬운 말로 설명합니다. ‘모르겠다’는 도움 요청이지 위임이 아닙니다. 추천은 채택 전까지 제안입니다. 명시적 위임은 정해진 범위에만 적용하며 선택 이유·가정을 보고합니다. 해당 없음·보류에도 이유와 재검토 조건을 남깁니다. 미결정 사항만 묻고 침묵을 승인으로 해석하지 않습니다.

3. 소프트웨어 기본 지침

OOAD 방법 선택을 요구하지 않고 프로젝트 전반의 역할과 책임 경계를 정합니다. 내부 객체의 협력은 AI가 구체화합니다. 명확히 문서화하고 합의한 아키텍처를 따릅니다. 모듈 책임, 허용되는 의존 방향, 도메인·데이터 소유권, 공개 계약, 외부 시스템 경계, 오류 처리를 명시합니다. 프로젝트 규모에 맞는 이유를 설명하며 계층·서비스·프레임워크를 임의로 늘리지 않습니다.

SOLID·GRASP의 책임 배분과 의존성 원칙을 해당 프로그래밍 방식에 맞게 적용합니다. 높은 응집도, 낮은 결합도, 명확한 인터페이스·계약, 교체 가능한 인프라를 지향합니다. 대체 가능성과 의존 경계를 검토합니다. 추측에 의한 추상화를 피하며 예외는 이유·영향을 기록합니다. 객체지향이나 특정 아키텍처를 강제하는 규칙은 아닙니다. Robert C. Martin의 SOLID 설명을 참고합니다. GRASP 참고 문헌은 Craig Larman의 Applying UML and Patterns 3판이며, 세부 규칙을 인용하기 전 해당 원문을 확인합니다.

입력 검증, 권한 경계, 비밀정보 관리, 데이터 수명, 복구 가능한 실패, 운영 관측을 서비스에 맞게 정의합니다. 요구사항·위험 경계에 테스트를 연결합니다. 빌드·테스트·릴리스·롤백·유지보수 책임을 기록하며 검증 계획과 실제 결과를 구별합니다.

4. 디자인 기본 지침

사용자 흐름, 정보 위계, 탐색 구조, 레이아웃, 타이포그래피, 색상·간격 토큰, 재사용 컴포넌트, 상호작용 규칙을 정의합니다. 상위 서비스의 제약을 존중합니다. 서비스 목적에 맞는 일관성을 유지하고 의도적인 변형은 이유를 기록합니다.

초기·로딩·빈 상태·성공·오류·비활성·복구 상태를 설계합니다. 반응형 읽기 순서, 의미 있는 레이블, 키보드 조작, 보이는 포커스, 대비, 대체 텍스트, 동작 감소를 정합니다. 웹은 WCAG 2.2 AA를 접근성 목표로 삼고 적용할 검증을 명시합니다. 검증 없이 준수를 선언하지 않습니다. 네이티브는 플랫폼 지침도 확인합니다. 시각 스타일은 핵심 작업을 지원해야 하며 사용성·접근성을 대신할 수 없습니다.

5. 기획 산출물을 확정한 뒤 개발하기

입력받은 이름·설명·맥락, 번호가 있는 요구사항, MVP·비목표, 측정 가능한 완료 조건, SW 아키텍처, 디자인 명세, 카탈로그 검토표를 작성합니다. 결정 기록에는 대안, 근거, 제안·채택·위임 상태, 정확한 위임 범위, 영향, 재검토 조건을 남깁니다. 위험·미확정 사항, 의존 순서에 따른 작업 목록, 요구사항별 검증 계획을 추가합니다.

지침 버전·리비전, 카탈로그 조회일, 선택한 글 ID·언어·리비전·URL을 기록합니다. 지침 버전은 실시간 카탈로그를 고정하지 않습니다. 재현을 위해 조회한 목록 사본이나 선택 기록을 보존합니다.

남은 차단 사항과 전체 기획안을 보여주고 확정받습니다. 개발을 막는 선택은 먼저 해결하고 차단하지 않는 보류 항목은 명시합니다. 기획 위임은 개발 허가가 아닙니다. 기획 확정과 개발 요청을 받으면 승인된 범위를 실행하며 같은 권한을 반복해서 묻지 않습니다. 범위 밖 변경은 새 결정을 받습니다.

6. 함께 키우는 지침과 버전

누구나 표현 개선, 빠진 주제, 반례, 번역, 시나리오 개선을 이슈나 PR로 제안할 수 있습니다. 기여·버전 규칙에 따라 문제, 변경 전후 동작, 출처, 기대 결과를 함께 남깁니다. 비공개 프로젝트 정보는 올리지 않습니다.

v2가 나와도 v1은 유지합니다. 동작을 바꾸지 않는 설명 수정은 리비전과 변경 이력을 갱신합니다. 의무·절차가 달라지면 새 주 버전을 만듭니다. 이전 버전 URL을 몰래 교체하지 않습니다. API schemaVersion 1과 지침 버전은 별개입니다. 새 버전은 관리자의 검토를 거치며 프로젝트는 명시적으로 업그레이드합니다.