화면 명칭과 AI에게 수정 요청하기
- 이 사이트에서는 주제별 문서 묶음을
덱, 주소 하나로 여는 문서를페이지, 왼쪽 메뉴의 페이지 묶음을사이드바 그룹이라고 부른다. 덱 사이드바는 페이지 사이를,페이지 목차는 한 페이지 안의 절 사이를 이동하는 메뉴다.- 파일 경로나 구현 문법을 몰라도 화면의 이름과 URL로 수정 위치를 전달할 수 있다.
- AI에게는 페이지 URL과 절 제목·요소 이름을 함께 주고, 원하는 변화와 적용 범위를 적는다.
“Starlight 페이지 모음의 목차를 바꿔줘”라고 하면 덱 전체인지, 왼쪽 메뉴의 묶음인지, 한 페이지 오른쪽의 목차인지 알기 어렵다. 내용의 단위와 화면의 영역을 구분해서 부르면 AI와 수정 대상을 맞추기 쉽다.
이 페이지는 사이트를 읽고 고치는 사람이 사용할 공통 용어를 정한다. 파일명이나 컴포넌트 이름을
몰라도 화면의 이름과 URL로 요청할 수 있다. AI가 고칠 파일은 저장소 지침과 실제 구조에서 찾는다.
아래 용어 중 덱은 이 저장소의 관례이며,
Starlight의 모든 사이트에 통용되는 공식 명칭은 아니다. 여기서는 슬라이드 묶음을 뜻하지 않는다.
이 장에서 처음 나오는 말3개
덱Deck- Starlight·Keycloak처럼 한 주제를 다루는 문서 묶음. 이 사이트에서는 덱 하나가 topic 하나와 대응한다.
사이드바 그룹Sidebar group- 덱 사이드바에서 시각적으로 이해하기·검토와 공유 같은 이름 아래 묶인 페이지들.
절Section- 페이지 본문을 제목으로 나눈 내용 단위. 큰 절은 h2, 그 안의 하위 절은 h3 제목을 쓴다.
덱·페이지·페이지 모음을 구분한다
섹션 제목: “덱·페이지·페이지 모음을 구분한다”| 부를 이름 | 가리키는 범위 | 이 사이트의 예 |
|---|---|---|
| 사이트 | 모든 덱과 사이트 홈을 포함한 전체 | Study Note |
| 덱 | 한 주제의 개요와 본문 페이지 전체 | Starlight 덱 |
| 사이드바 그룹 | 한 덱의 왼쪽 메뉴에서 이름 아래 묶인 페이지들 | Starlight 덱의 시각적으로 이해하기 그룹 |
| 페이지 | 고유한 URL로 여는 문서 하나 | LearningFlow 페이지 |
| 절 / 하위 절 | 페이지 안에서 제목으로 나눈 내용 | 예제를 직접 읽는다 절 |
| 블록 / 요소 | 절 안의 특정 코드·표·그림·버튼 등 | 요청 예시 코드 블록, 인터랙티브 예제, 다음 단계 버튼 |
페이지 모음도 일상적인 표현으로는 괜찮다. 다만 주제 전체라면 덱, 메뉴의 묶음이라면
사이드바 그룹, 임의로 고른 여러 문서라면 각 페이지의 제목이나 URL 목록으로 지정한다.
예를 들어 “시각적으로 이해하기 그룹의 세 페이지”와 “Starlight 덱 전체”는 범위가 다르다.
사이드바 그룹은 읽는 순서를 묶는 단위다. 시각적으로 이해하기라는 그룹이 있어도 그 이름이 URL 앞에 붙지는 않는다.
페이지 순서를 바꾸는 일과 페이지 주소를 바꾸는 일은 별개다.
문서 화면의 각 부분을 부른다
섹션 제목: “문서 화면의 각 부분을 부른다”아래는 2026-09-29 LearningFlow 페이지의 데스크톱 화면에 설명용 이름표를 붙인 것이다. 개편 전 제목·그룹명이 보이지만 이름표가 가리키는 화면 영역의 역할은 같다. 왼쪽 C는 다른 페이지로 가는 메뉴, 오른쪽 I는 현재 페이지 안에서 이동하는 목차라는 차이를 먼저 본다. 이미지를 누르면 확대할 수 있다. 모바일에서는 메뉴가 접히거나 위치가 달라지지만 역할을 기준으로 같은 이름을 쓴다.
| 표시 | 이름 | AI에게 가리킬 때 |
|---|---|---|
| A | 헤더 | 상단의 사이트 이름·현재 덱 이름·검색·테마 버튼이 있는 영역 |
| B | 덱 전환기 | 왼쪽 위에서 Starlight·Keycloak 등 다른 덱을 고르는 드롭다운 |
| C | 덱 사이드바 | 현재 덱의 페이지를 나열하는 왼쪽 메뉴 |
| D | 사이드바 그룹 | 사이드바의 콘텐츠처럼 펼치고 접는 페이지 묶음 |
| E | 페이지 링크 | 사이드바에서 LearningFlow로 단계별 흐름 설명하기처럼 페이지를 여는 항목 |
| F | 페이지 제목 | 가운데 맨 위의 큰 제목. 본문의 h2·h3 절 제목과 구별한다 |
| G | 본문 | 페이지의 설명·절·코드·표·예제가 놓이는 가운데 영역 |
| H | 절 제목 | 본문을 나누는 제목. 해당 절의 내용까지 바꿀지, 제목만 바꿀지 함께 말한다 |
| I | 페이지 목차(TOC) | 오른쪽의 목차. 현재 페이지의 절·하위 절로 이동한다 |
| J | 결론 상자(Thesis) | 본문 첫머리의 결론부터 상자 |
“목차”만 말하면 C와 I가 모두 떠오른다. 페이지 순서를 바꾸려면 덱 사이드바, 한 문서 안의 제목 구성을 바꾸려면 페이지 목차와 해당 절이라고 말한다. 페이지 목차는 본문의 절 제목에서 만들어지므로, 제목 자체를 바꾸는 요청인지 목차의 표시 방식을 바꾸는 요청인지도 구별한다.
본문 안에서는 블록 이름을 더한다
섹션 제목: “본문 안에서는 블록 이름을 더한다”블록만으로 대상을 정하기 어렵다면 보이는 제목이나 첫 줄을 덧붙인다.
같은 컴포넌트라도 한 페이지의 내용만 고치는 일과 모든 사용처의 모양을 고치는 일은 범위가 다르다.
| 보이는 것 | 쓸 이름 | 위치를 좁히는 예 |
|---|---|---|
이 장에서 처음 나오는 말 상자 | 용어 상자(TermIntro) | “첫머리 용어 상자의 보관 상태 설명” |
| 복사할 수 있는 소스 코드 | 코드 블록 | “다른 페이지에 적용을 요청한다 절의 요청 예시” |
| 본문에서 직접 조작할 수 있는 화면 | 렌더링 예제 / 인터랙티브 예제 | “LearningFlow 예제의 단계 선택기” |
| 행과 열로 비교하는 내용 | 표 | “시각 표현 페이지의 표현 선택 표” |
| 덱 개요에서 학습 흐름을 보여 주는 구성도 | 덱 구성도(DeckMap) | “Starlight 덱 개요의 구성도에서 시각적으로 이해하기 항목” |
사이트 홈과 덱 개요를 구분한다
섹션 제목: “사이트 홈과 덱 개요를 구분한다”**사이트 홈(랜딩)**은 전체 덱을 찾는 /이고, 덱 개요는
Starlight 덱을 소개하는 /starlight/다. 덱 개요도 페이지 하나이며,
왼쪽 사이드바에서는 개요로 표시된다. “메인 페이지” 대신 어느 쪽을 뜻하는지 말한다.
| 표시 | 이름 | 가리키는 것 |
|---|---|---|
| A | 전역 검색 | 문서 내용을 찾는 헤더의 검색 버튼 |
| B | 덱 이름 검색 | 홈에서 이름으로 덱 목록을 좁히는 입력란 |
| C | 태그 필터 | 쿠버네티스·프론트엔드처럼 관심 주제로 덱을 좁히는 버튼들 |
| D | 보기 전환 | 덱 목록을 카드 또는 테이블로 보는 버튼 |
| E | 덱 목록 | 홈에 나열된 여러 덱. 현재 화면은 테이블 보기 |
| F | 카테고리 | 도구 · 작업 환경처럼 덱을 분류한 큰 묶음. 덱 안의 사이드바 그룹과 다르다 |
| G | 덱 항목 | 덱 하나를 소개하고 덱 개요로 연결하는 행. 카드 보기에서는 덱 카드 |
“검색을 고쳐줘” 대신 전역 검색의 결과인지 홈의 덱 이름 검색인지 지정한다. “카테고리를 바꿔줘”와 “사이드바 그룹을 옮겨줘”도 서로 다른 요청이다.
수정 요청에는 위치·막힌 점·원하는 결과를 적는다
섹션 제목: “수정 요청에는 위치·막힌 점·원하는 결과를 적는다”정확한 컴포넌트 이름을 알 필요는 없다. URL과 화면에 보이는 글자를 함께 주면 대상을 찾기 쉽다. 다른 표현을 쓰더라도 AI가 문맥에서 대상을 식별할 수 있으면 진행하도록 한다.
- 위치: 덱·페이지 이름과 URL, 필요한 경우 절 제목이나 요소를 적는다.
- 막힌 점: 무엇이 안 보이거나 어느 설명부터 이해가 안 되는지 적는다.
- 원하는 결과: 바뀐 뒤 무엇을 읽거나 비교할 수 있어야 하는지 말한다.
- 범위: 이 페이지의 내용인지, 여러 페이지인지, 사이트 전체의 공통 화면인지 정한다.
한 페이지의 설명을 고친다
섹션 제목: “한 페이지의 설명을 고친다”
/starlight/learning-flow/의 ‘예제를 직접 읽는다’ 절에서, 첫 단계와 두 번째 단계 사이에 무엇이 달라졌는지 잘 모르겠어. 브라우저의 보관 상태를 짚어 설명하고 확인 질문을 넣어줘. 이 페이지의 설명을 다듬어줘.
여러 페이지의 순서를 바꾼다
섹션 제목: “여러 페이지의 순서를 바꾼다”Starlight 덱 사이드바의 ‘시각적으로 이해하기’ 그룹에서 LearningFlow 페이지를 ‘내용에 맞는 시각 표현 고르기’ 바로 뒤로 옮겨줘. 페이지 주소와 본문은 유지해줘.
공통 화면의 동작을 고친다
섹션 제목: “공통 화면의 동작을 고친다”모든 덱의 덱 사이드바에서 현재 페이지 링크가 더 잘 보이게 해줘. 밝은 테마와 어두운 테마 모두에서 확인해줘. 사이트 공통 화면의 변경이야.
특정 예제의 문제라면 “요청·응답 예제의 다음 단계 버튼”처럼 좁힌다. 모바일에서만 생기는 문제는 기기나 화면 폭을 덧붙인다. 절 제목 옆의 링크를 복사하거나 화면을 첨부하면 위치를 전달하는 데 도움이 된다.
AI가 찾을 파일은 역할만 알아 둔다
섹션 제목: “AI가 찾을 파일은 역할만 알아 둔다”본문을 수정할 때 파일을 직접 지정할 필요는 없다. AI의 변경 보고에 아래 이름이 나오면 무엇을 바꿨는지 구별할 수 있는 정도면 충분하다.
- AGENTS.md AI의 작업 진입점
디렉터리docs/ AI가 따를 작성·검증·운영 지침
- …
디렉터리src/
디렉터리content/docs/starlight/ Starlight 덱
- _baseline.md 독자·범위·이 덱의 작성 기준
- _deck.mjs 덱 정보·사이드바 그룹·페이지 순서·덱 구성도
- index.mdx 덱 개요
- learning-flow.mdx 페이지 제목·설명·본문
디렉터리components/ 문서 요소와 사이트 공통 화면
- …
- styles/custom.css 사이트 전역 스타일
_baseline.md는 어떤 문서를 쓸지의 기준, _deck.mjs는 어떻게 묶고 나열할지의 설정이다.
본문은 각 MDX 파일에 있다. 작성 규칙과 기준 파일 자체는 사이트의 학습 페이지로 나오지 않는다.
한 페이지의 문장을 고쳤다면 주로 본문이, 여러 덱에 쓰는 버튼 동작을 고쳤다면 공용 컴포넌트가 바뀐다.
반복해서 적용할 선호는 “이 덱의 작성 기준에도 반영해줘”라고 요청할 수 있다. AI는 공통 작성 규칙과 해당 덱의 기준을 함께 확인하며, 세부 구현·검증은 그 지침을 따른다.
피드백이 반영됐는지 확인한다
섹션 제목: “피드백이 반영됐는지 확인한다”수정 결과에서 처음 막혔던 부분을 다시 읽는다. “설명과 그림을 늘렸는가”보다 이제 해당 질문에 답할 수 있는가를 본다. 여전히 어렵다면 같은 위치에서 어떤 관계가 남았는지 이어서 말한다.
“목차를 바꿔줘”라는 말이 모호했다면 페이지 순서인지 절 순서인지 덧붙이면 된다. 처음부터 완벽한 요청을 쓰기보다 결과를 보며 수정 범위를 좁혀 가는 방식이다.