AI와 함께 지식을 쌓는 방식

결론부터

• 목표는 많이 저장하는 것이 아니라, 나중에 읽어도 이해되고 필요한 설명을 다시 찾을 수 있게 정리하는 것이다.
• AI가 자료를 확인하고 문서를 만들면, 사람은 화면을 읽으며 막힌 지점을 피드백한다.
• Starlight는 글과 시각 자료를 함께 보여 주고 검색·탐색·공유할 웹 문서의 틀을 제공한다.

이 장에서 처음 나오는 말1개

덱Deck

한 주제를 다루는 문서 묶음. 슬라이드가 아니라 검색하고 다시 읽는 학습 노트다.

대화에서 이해한 내용도 며칠 뒤에는 “왜 그랬지?”라는 질문으로 돌아온다. 대화 전체를 다시 읽는 대신, 질문에 답하는 페이지와 그 안의 예제·그림을 찾아볼 수 있으면 좋다. 이 사이트에서는 한 주제를 덱으로 묶고, 다시 찾을 질문마다 페이지를 만든다.

AI와 사람이 맡는 일

AI가 만드는 것

공식 근거를 확인하고 설명·예제·시각 자료를 작성한다. 페이지를 연결하고, 화면 구현과 오류 수정·검증까지 수행한다.

사람이 판단하는 것

무엇을 배우려는지 정한다. 완성된 화면을 읽고 설명할 수 있는지, 어디서 막히는지 판단해 다음 수정을 요청한다.

사람이 파일을 직접 편집하는 능력은 이 흐름의 전제가 아니다. 대신 “이 문단 뒤부터 이해가 안 된다”, “버튼을 눌렀을 때 무엇이 달라졌는지 모르겠다”처럼 읽는 경험을 구체적으로 전달하는 것이 중요하다. AI가 쓴 설명의 근거와 예제도 AI에게 재확인하게 할 수 있다. 그럴듯한 화면만으로 정확성을 판단하지는 않는다.

한 번의 초안에서 끝내지 않는다

1. 질문을 준다. 배우려는 주제, 이미 아는 내용, 읽고 나서 할 수 있기를 바라는 일을 말한다.

2. AI가 문서를 만든다. 자료 확인부터 본문·그림·예제·검증까지 맡긴다.

3. 사람이 결과를 읽는다. 예제를 따라가고, 그림이나 상호작용으로 핵심을 설명해 본다.

4. 막힌 지점을 고친다. 해당 페이지와 이해되지 않은 관계를 알려 주고 수정된 설명을 다시 읽는다.

예를 들어 로그인 문서에 “인증 후 토큰을 받는다”만 쓰여 있다면, “누가 토큰을 받으며 브라우저에는 무엇이 남는가?”라고 피드백한다. AI는 이 질문에 맞춰 메시지와 보관 상태를 나눈 예제를 만들 수 있다. 반복할수록 문서는 자신이 실제로 이해한 방식에 가까워진다.

글에 그림과 조작을 더하는 이유

읽다가 막히는 이유	웹 문서에서 할 수 있는 것
이름은 많은데 서로의 관계가 안 보인다	다이어그램에서 경계와 연결을 한눈에 본다
제품 화면의 어디를 말하는지 모르겠다	실제 화면 이미지에 위치와 읽을 지점을 표시한다
여러 단계의 설명을 동시에 기억하기 어렵다	이전·다음 버튼으로 한 단계의 전달 값과 상태만 본다
나중에 필요한 설명을 다시 찾기 어렵다	제목·본문을 검색하고 해당 절의 링크로 돌아온다

시각 자료가 본문과 함께 있어야 그림을 본 뒤에도 용어·조건·근거를 다시 확인할 수 있다. 이 덱의 화면 안내와 단계별 흐름 예제가 실제 사례다.

Astro와 Starlight는 이 정도만 알면 된다

Astro는 파일과 컴포넌트를 웹 페이지로 만들고, Starlight는 문서를 읽는 화면과 탐색·검색을 제공한다. Starlight 공식 소개에서 기본 기능을 확인할 수 있다. 이 저장소는 그 위에 덱별 탐색, 다이어그램, 이미지 확대, 학습용 컴포넌트를 더했다.

사람이 이 내부 구조를 배워야 문서 작성을 맡길 수 있는 것은 아니다. 소스 파일을 다룰 AI가 저장소 지침을 읽고 알맞게 구현하도록 하면 된다. 어떤 도구를 택했는지가 궁금할 때는 문서 도구 선택을 읽고, 바로 정리하고 싶다면 작성 요청으로 이동한다.

이 사이트에서 더한 플러그인

플러그인은 기본 문서 화면에 기능이나 테마를 더하는 확장이다. 아래 이름은 각각 공식 안내로 연결된다. 사람이 설치법을 외울 필요는 없지만, 화면에서 쓰는 기능이 어디에서 오는지는 알아볼 수 있다.

확장	이 사이트에서 하는 일	종류
Starlight Sidebar Topics	덱마다 별도의 사이드바를 제공해 서로 다른 학습 주제를 나눈다	Starlight 플러그인
Starlight Rapide	문서 화면의 색과 스타일에 테마를 적용한다	Starlight 테마 플러그인
Starlight Image Zoom	본문 이미지와 다이어그램을 눌러 확대한다	Starlight 플러그인
Astro D2	AI가 작성한 D2 텍스트를 다이어그램 이미지로 만든다	Astro 통합

이 목록은 현재 사이트 설정에서 사용하는 확장이다. 덱 전환 드롭다운의 모양과 접기 동작, 덱 자동 등록, LearningFlow는 이 저장소의 자체 코드가 맡는다. 검색은 Starlight가 기본 제공하는 Pagefind를 사용한다. 따라서 플러그인을 추가하는 일과 학습용 컴포넌트를 만드는 일은 필요한 결과에 맞춰 나눠 요청한다.

AI에게 문서 작성 요청하기배우려는 질문을 문서와 예제로 바꾸는 요청 예시.