프로젝트 문서(Project Docs)
소프트웨어 프로젝트의 전체 문서 세트를 생성하고 최신 상태로 유지하며, 고정된 구조와 AGENTS.md 및 MEMORY.md 간의 고정된 관계를 따릅니다. 사용자가 처음부터 문서를 생성하거나, 변경 후 새로 고치거나, 파일 간 일관성을 유지하려고 할 때 사용하세요.
대상 구조
이 스킬이 관리하는 모든 프로젝트는 다음 레이아웃을 지향해야 합니다:
mi-proyecto/
├── README.md # 무엇이며, 어떻게 실행하는지
├── AGENTS.md # 에이전트를 위한 규칙 및 지침
├── MEMORY.md # 현재 결정 사항 및 기각된 사항
├── CHANGELOG.md # 버전 간 변경 사항
├── DESIGN.md # 시각적 디자인 시스템 (UI가 있는 경우에만)
└── docs/
├── architecture.md
├── plans/ # 에이전트 계획, 파일별 하나씩
└── (OpenAPI + Scalar served from the API at /docs)
프로젝트에 이미 일부 파일이 있는 경우 먼저 읽고 제자리에서 업데이트하세요. 무턱대고 덮어쓰지 마세요. 파일이 누락된 경우 아래 해당 템플릿에 따라 생성하세요.
워크플로우
- 현황 조사 프로젝트 루트와
docs/디렉터리를 나열하여 어떤 파일이 이미 있는지 확인합니다. 기존AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md가 있으면 전체를 읽습니다. 이 파일들은 설계상 짧습니다. - 범위 파악 사용자가 특정 파일을 언급하면(예: "CHANGELOG 업데이트") 해당 파일에 집중하지만, 변경 사항이
MEMORY.md나AGENTS.md로 전파되어야 하는지 여전히 확인합니다(전파 규칙 참조). 사용자가 "프로젝트 문서화" 또는 "문서 업데이트"처럼 일반적인 요청을 하면 위 구조의 모든 파일을 검토합니다. - 사실 수집 코드베이스 자체(패키지 매니페스트, 진입점, 스크립트, 라우트, 최근 커밋)에서 필요한 정보를 수집하고 추측하지 마세요. 명령어, 스택 세부 정보, 엔드포인트를 지어내지 말고 코드나 설정 파일을 읽어 확인하세요.
- 각 파일 작성 또는 업데이트 해당 참조 템플릿을 사용합니다.
AGENTS.md(~30-40줄)와MEMORY.md(~50줄)의 엄격한 길이 제한을 준수하세요. 이는 제안이 아니라 필수 제약 조건입니다. 에이전트는 매 세션마다 이 파일들을 다시 읽기 때문에 너무 길어지면 유용성이 떨어집니다. - 결과 보고 생성된 파일과 업데이트된 파일을 구분하여 보고하고, 확인할 수 없는 항목(예: "테스트 명령어를 찾지 못했습니다. 확인해주세요")을 표시합니다.
문서
README.md
"이것이 무엇이며 어떻게 실행하는지"를 사람에게 설명합니다. references/readme-template.md를 참조하세요. 실행/설치/테스트 명령어는 프로젝트의 실제 스크립트(package.json, Makefile, pyproject.toml 등)에서 가져오세요. 명령어 이름을 추측하지 마세요.
AGENTS.md
이 저장소에서 작업하는 코딩 에이전트를 위한 지침입니다. 정확한 섹션과 순서는 references/agents-template.md를 참조하세요. 하드 제한: 총 ~30-40줄. 이미 더 긴 경우 업데이트할 때 추가하는 것만큼이나 줄이는 것도 작업입니다. 일시적인 결정이나 진행 중인 메모처럼 보이는 것은 MEMORY.md로 옮기고, 여기에는 내구성 있는 규칙만 유지하세요.
MEMORY.md
세션 간 메모리: 현재 사실, 주요 결정의 이유, 시도했지만 기각된 것, 다음 단계. references/memory-template.md를 참조하세요. 하드 제한: ~50줄. 업데이트할 때 능동적으로 정리하세요. 더 이상 중요하지 않은 항목은 삭제하거나 압축하여 파일이 계속 커지는 것을 방지하세요.
AGENTS.md와 MEMORY.md의 관계 (핵심 규칙이므로 정확히 이해하세요):
AGENTS.md에는 에이전트가 작업 시작 시MEMORY.md를 읽고 작업 종료 시 업데이트하도록 지시하는 짧은 "메모리" 섹션이 포함되어야 합니다. 다음 기본 문구를 사용하되 프로젝트에서 이미 다른 방식으로 표현하고 있는 경우에만 조정하세요:## Memoria - Al empezar, lee `MEMORY.md` para conocer el estado del proyecto y las decisiones tomadas. - Al terminar una tarea, actualízalo: estado actual, decisiones importantes (con su porqué) y errores a evitar. - Mantenlo breve (máximo ~50 líneas): resume o elimina lo que ya no aporte. - Si algo se convierte en una regla permanente, propón moverlo a `AGENTS.md` en lugar de dejarlo en la memoria. - No guardes nunca datos sensibles (claves, tokens, datos personales).AGENTS.md의 "제한 사항" 섹션에는✅ 항상: 각 작업 완료 시 MEMORY.md 업데이트가 포함되어야 합니다.- 전파 규칙:
MEMORY.md는 현재 사실(현재 상태, 이유가 있는 결정, 교훈, 다음 단계)을 보관합니다.AGENTS.md는 항상 사실인 것(영구 규칙, 관례, 스택, 제한 사항)을 보관합니다.MEMORY.md의 어떤 것이 일회성 결정이 아니라 상시 규칙이 되면(예: "우리는 X를 절대 사용하지 않기로 결정"이 "X는 절대 사용하지 않음"으로 바뀌는 경우) 이를AGENTS.md로 옮기고MEMORY.md에서 제거하세요. 두 파일 중 하나를 업데이트할 때마다 이 승격이 발생해야 하는지 항상 확인하세요. - 두 파일 모두에 비밀, 토큰 또는 개인 데이터를 절대 작성하지 마세요.
CHANGELOG.md
"버전 간 변경 사항"을 설명합니다. Keep a Changelog 규칙(각 버전 아래 Added/Changed/Fixed/Removed, 최신 버전이 상단, 진행 중인 작업을 위해 맨 위에 Unreleased 섹션)을 따릅니다. references/changelog-template.md를 참조하세요. 업데이트할 때 작업이 발생하면 Unreleased 아래에 항목을 추가하고, 사용자가 릴리스를 표시할 때만 새로운 날짜 버전 섹션을 만듭니다.
DESIGN.md
"어떻게 보이며 UI를 어떻게 구축해야 하는지"를 설명합니다. 즉, UI를 생성하는 에이전트가 읽는 시각적 디자인 시스템입니다. 프로젝트 루트(docs/ 아님)에 위치하며 AGENTS.md 옆에 있습니다. 공개된 Google Stitch DESIGN.md 형식을 따릅니다(spec: github.com/google-labs-code/design.md, 현재 alpha). 각 블록에 대한 템플릿과 설명은 references/design-template.md를 참조하세요.
- 사용자 인터페이스(웹, 모바일, 데스크톱)가 있는 프로젝트에만 해당합니다. 프로젝트가 UI가 없는 순수 API/CLI/라이브러리인 경우 생성하지 말고 보고서에 그렇게 명시하세요.
- 두 계층: 기계가 읽을 수 있는 토큰(
colors,typography,rounded,spacing,components)이 포함된 YAML 프론트매터(이것이 규범적 값임)와 이유를 설명하는 마크다운 본문입니다. 토큰은 무엇을 말하고, 산문은 언제, 왜를 말하며, 16진수 코드를 반복하는 대신 토큰 이름을 참조합니다. - 섹션 순서는 고정입니다: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts. 이 제목을 정확히 영어로 유지하세요(도구가 이름으로 일치시킵니다; 별칭
Brand & Style,Layout & Spacing및Elevation도 허용됨). 산문은 프로젝트 언어로 작성하세요. 섹션은 생략할 수 있지만 순서를 바꿀 수 없으며 중복된 제목은 오류입니다. 추가 섹션(예: Iconography & Imagery, Motion, Accessibility)은 허용되며 항상 Do's and Don'ts 뒤에 배치하세요. - 코드에서 값을 가져오고 절대 만들어내지 마세요: Tailwind 설정, CSS 변수(
:root,globals.css), UI 라이브러리 테마 파일, 로드된 글꼴, Figma/DTCG 토큰 내보내기. 프로젝트에 UI가 있지만 정의된 시각적 아이덴티티가 없는 경우 값을 제안하고 보고서에 "제안, 확인 필요"로 표시하세요. DESIGN.md가 이미 존재하는 경우 읽고 제자리에서 업데이트하세요. 조용히 덮어쓰지 마세요. 색상, 글꼴 또는 간격이 변경될 때 토큰을 코드와 동기화 상태로 유지하세요.- 엄격한 줄 제한은 없지만(참조 문서인
docs/architecture.md와 같음) 각 섹션을 집중적으로 유지하세요: 3-6개의 글머리 기호 또는 짧은 단락. - 검증: Node를 사용할 수 있는 경우
npx @google/design.md lint DESIGN.md를 실행하고 오류(broken-ref)와 합리적인 경고(missing-primary,contrast-ratio,section-order)를 수정합니다. 그렇지 않으면 사용자에게 명령어를 알려주세요. AGENTS.md가 존재하고DESIGN.md를 언급하지 않는 경우, 사용자에게(스스로 적용하지 말고) UI 에이전트가 UI를 생성하기 전에 읽도록 한 줄 포인터를 추가할 것을 제안하세요.AGENTS.md의 ~30-40줄 제한을 염두에 두세요.
docs/architecture.md
"어떻게 구축되었는지"를 설명합니다: 구성 요소, 데이터 흐름, 주요 설계 결정 및 그 이유, 주목할 만한 제약 사항. references/architecture-template.md를 참조하세요. 이 문서는 매 세션마다 다시 읽는 것이 아니라 참조 문서이므로 다른 문서보다 길어질 수 있지만, 긴 산문보다는 다이어그램과 짧은 섹션을 선호하세요. 주요 구성 요소/데이터 흐름 보기를 위해 도움이 될 때 mermaid 다이어그램을 사용하세요.
docs/plans/
에이전트가 중요하지 않은 작업(다단계 구현 계획, 마이그레이션 계획, 리팩터링 계획)에 대한 계획을 생성할 때 이를 채팅에만 남기지 말고 여기에 자체 파일로 저장하세요. 디렉터리가 없으면 생성하세요. 파일 이름은 YYYY-MM-DD-short-slug.md(예: 2026-10-03-add-payment-webhook.md)로 지정하여 시간순으로 정렬되도록 하세요. 각 계획 파일은 자체적으로 완결되어야 합니다: 목표, 접근 방식, 단계, 열린 질문. 완료된 후에는 이전 계획을 삭제하지 마세요. 이는 기록입니다. 프로젝트에서 "완료" 표시를 원하면 파일을 제거하는 대신 파일 상단에 한 줄 상태 메모를 추가하세요.
API 문서 — OpenAPI + Scalar
이는 정적 마크다운 파일이 아닙니다. API에서 실시간으로 제공되며, 일반적으로 Scalar의 API 참조 렌더러가 OpenAPI 사양을 읽는 /docs 또는 /reference 경로에서 제공됩니다. API 문서 설정 또는 업데이트를 요청받으면:
- 프로젝트가 이미 OpenAPI 사양을 생성하는지 확인합니다(프레임워크 데코레이터/어노테이션,
openapi.yaml/openapi.json파일, 또는 이미 종속성에 있는 사양 생성 라이브러리). - 사양이 존재하지만 아직 Scalar를 통해 제공되지 않는 경우, 프로젝트 프레임워크에 대한 Scalar 미들웨어/핸들러를 연결합니다(Scalar는 대부분의 일반적인 백엔드 프레임워크에 대한 공식 통합을 제공합니다. 이 생태계는 빠르게 변화하므로 가정하지 말고 현재 패키지 이름/API를 확인하세요).
/docs에 마운트합니다. - 사양이 아직 없는 경우, 기존 라우트/핸들러에서 사양을 생성합니다(대부분의 프레임워크에는 라우트 정의/타입에서 OpenAPI를 파생하는 라이브러리가 있습니다. 수동으로 YAML을 작성하는 것보다 이것을 선호하세요). 그런 다음 Scalar를 연결합니다.
- 프레임워크가 코드에서 파생할 수 있다면 거대한 정적 OpenAPI YAML을 수동으로 유지 관리하지 마세요. 즉시 동기화가 어긋납니다. 코드 우선 생성을 선호하세요.
- 설정이 완료되면
README.md에/docsURL을 기록하여 사람들이 위치를 알 수 있도록 하세요.
완료 전 확인 목록
-
AGENTS.md는 ≤ ~40줄이며MEMORY.md를 가리키는 "메모리" 섹션이 있습니다. -
MEMORY.md는 ≤ ~50줄이며AGENTS.md에 속하는 영구적인 내용이 남아 있지 않습니다. -
README.md명령어는 가정된 것이 아니라 실제 프로젝트 구성을 기준으로 확인되었습니다. -
CHANGELOG.md는 Keep a Changelog 형식을 따르며Unreleased섹션이 있습니다. -
DESIGN.md(프로젝트에 UI가 있는 경우에만)는 프로젝트 루트에 있으며, 토큰은 실제 코드와 일치하고, 섹션은 표준 순서를 따르며,npx @google/design.md lint DESIGN.md에서 오류가 보고되지 않습니다. -
docs/architecture.md는 현재 구조를 반영하며, 오래된 구조가 아닙니다. - 새로운 에이전트 계획은 날짜가 포함된 파일 이름으로
docs/plans/아래에 저장됩니다. - 민감한 정보(키, 토큰, 개인 데이터)가 어떤 문서에도 작성되지 않았습니다.