결과를 검토하고 다시 찾기

결론부터

• 문서를 읽고 예제의 결과를 설명할 수 있는지가 사람의 핵심 검토 기준이다.
• AI는 근거·예제를 대조하고 자동 검사를 수행한다. 검사 통과가 설명의 정확성과 이해를 보장하지는 않는다.
• 다시 찾을 용어와 안정적인 링크를 남기고, 시간이 지나 달라진 내용은 근거를 재확인해 갱신한다.

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

의미 리뷰

설명·그림·예제의 정확성과 적용 조건을 근거에 비춰 확인하는 일.

빌드Build

저장소의 문서와 컴포넌트를 브라우저에서 읽을 웹 파일로 만드는 과정.

“작성이 끝났고 검사도 통과했다”는 보고를 받았어도 읽다가 막힐 수 있다. 이때는 더 많은 내용을 추가하기보다 어느 질문에 아직 답하지 못하는지를 확인한다. 이 페이지는 완성 보고부터 재방문까지 문서를 어떻게 발전시킬지 다룬다.

읽고 설명할 수 있는지 본다

확인할 것	결과에서 볼 증거	부족할 때 피드백
핵심 결론	첫 화면에 중심 질문의 답이 드러난다	내용을 예고하는 대신 이 질문의 답을 먼저 보여줘
설명의 연결	문제·원리·예제가 이어진다	이 예제가 앞의 원리에서 어떻게 나오는지 연결해줘
예제의 결과	입력과 예상 결과를 비교할 수 있다	무엇을 넣고 어떤 결과를 봐야 하는지 적어줘
시각 자료	그림의 읽을 지점과 관계를 말할 수 있다	화살표 의미와 각 주체가 가진 값을 구분해줘
근거와 조건	주장 가까이에 공식 출처와 적용 조건이 있다	이 설명의 기준 버전과 근거를 다시 확인해줘

검색으로 처음 들어온 사람처럼 해당 페이지 하나만 읽어 보아도 좋다. 앞 페이지를 기억해야만 이해된다면 필요한 전제와 선행 개념 링크를 보완하게 한다.

AI의 검증 보고를 읽는다

이 저장소에서 사이트 본문·코드·설정을 바꾸면 AI는 마지막에 npm run check를 실행한다. 이 명령은 콘텐츠 규칙 검사, 사이트 빌드, 생성된 페이지의 내부 링크 검사를 묶은 프로젝트 명령이다. Astro의 타입 검사 명령과는 다르다.

보고된 확인	알 수 있는 것	별도로 볼 것
콘텐츠 검사 통과	필수 정보와 페이지 등록 등 저장소 규칙이 맞는다	문서 구성이 학습 질문에 맞는가
빌드 통과	MDX·컴포넌트·D2를 페이지로 만들 수 있다	설명과 화살표가 사실에 맞는가
내부 링크 검사 통과	생성된 페이지·이미지·절의 내부 참조가 연결된다	외부 출처가 주장을 뒷받침하는가
변경한 화면 확인	검사한 배치·조작이 기대대로 보인다	독자가 의미를 이해할 수 있는가

새 그림은 렌더 결과를 확인하고, 새 동작이나 레이아웃 변경은 필요한 대표 페이지에서 확인한다. 문장·링크·페이지 순서만 바꿨다고 덱 전체의 브라우저 검사를 반복할 필요는 없다. AI는 검증 지침에 맞춰 범위를 정한다.

완료 보고에는 어느 페이지가 바뀌었는지, 어떤 검사를 실제로 실행했는지, 확인하지 못한 부분이 무엇인지가 있어야 한다. “검사하는 방법”만 적힌 것을 실행 완료로 읽지 않는다.

수정 요청으로 다시 연결한다

[페이지 URL]의 [절 제목]을 읽었는데 [이해되지 않는 점]이 남아 있어.
특히 예제의 [입력이나 단계]에서 왜 [결과]가 되는지 설명할 수가 없어.
그 연결을 보완하고, 필요하면 그림이나 예제를 바꿔줘.
근거와 예제의 의미를 다시 확인한 뒤 이번 변경에 맞게 검증해줘.

같은 문제가 여러 페이지에 반복되면 적용 범위를 덱 전체로 넓혀 달라고 말한다. 앞으로도 유지할 선호라면 “이 덱에서는 개념마다 실제 사례를 먼저 보여 주도록 작성 기준에 반영해줘”처럼 요청할 수 있다. 한 페이지의 수정이 다음 작성에도 이어진다.

검색으로 다시 찾는다

헤더의 전역 검색은 문서 내용을 찾는다. 홈의 덱 이름 검색은 목록에서 덱을 고른다. 예를 들어 보관 상태로 전역 검색하면 그 말을 설명하는 페이지를 찾는 데 도움이 된다. 페이지에 도착한 뒤에는 페이지 목차로 필요한 절로 이동한다.

Starlight의 Pagefind 검색은 빌드된 페이지를 바탕으로 한다. 새 내용이 안 보이면 최신 수정이 빌드·배포됐는지부터 확인한다. 페이지의 짧은 소개문과 검색 결과 발췌문이 항상 같은 것은 아니다.

원하는 말로 찾지 못했다면 “나는 이 내용을 [검색어]로 찾았는데 나오지 않았다”라고 피드백한다. AI가 제목·본문의 실제 용어와 필요한 별칭을 보완할 수 있다.

오래된 설명을 갱신한다

페이지의 검토 날짜는 실제 내용과 근거를 확인한 날짜다. 파일을 조금 고쳤다고 제품 기능까지 최신이라는 뜻은 아니다. 공식 문서나 실제 동작과 어긋남을 발견하면 페이지와 차이를 알려 주고 관련 예제·그림까지 함께 갱신하게 한다.

자주 참고하는 페이지는 처음부터 다시 읽기보다 자신이 적용할 조건과 예제가 여전히 맞는지 확인한다. 좋은 문서는 한 번 완성한 뒤 고정된 문서가 아니라, 다시 쓰면서 설명을 다듬을 수 있는 문서다.

웹으로 공유하기검토한 결과를 공개 주소와 절 링크로 전달한다.