기술 문서를 프로젝트 규칙대로, 링크를 깨뜨리지 않고 고치기

## 고치기 전에, 고쳐도 되는 파일과 자동 생성된 파일 구분하기 - 작성된 콘텐츠, 재사용 가능한 포함 항목, 템플릿, 구조화 데이터, 정적 자산, 생성된 참조 문서가 각각 어디에 있는지 확인합니다. - 저장소의 기여자 안내서, 스타일 가이드, 구성요소 참조 문서, 프런트 매터 규칙을 최우선 기준으로 삼습니다. - 변경하기 전에 편집 가능한 소스와 외부에서 공급되어 포함된 콘텐츠 또는 생성된 콘텐츠를 구분합니다. - 외부에서 공급된 파일이나 생성된 참조 페이지를 직접 편집하지 마세요. 해당 항목의 상위 원본을 추적하여 그곳에서 수정합니다. - 로컬 검증 실패가 보호된 콘텐츠에서 비롯된 경우, 로컬 우회 방법을 적용하지 말고 해당 콘텐츠를 담당하는 상위 원본을 보고합니다. ## 링크에 실제 파일 경로를 쓰고 연결 대상 확인하기 - 게시 시스템이 소스 경로를 다시 쓰거나, 경로 일부를 제거하거나, 별칭을 지정하는지 확인합니다. - 빌드 시스템이 소스 트리를 기준으로 링크를 해석한다면 공개 URL이 더 짧더라도 내부 참조에는 전체 소스 경로를 사용합니다. - 소문자 변환 및 슬러그 생성 규칙을 포함하여, 실제 렌더러가 생성한 제목 식별자와 앵커가 일치하는지 확인합니다. - 대체 링크를 추측하지 말고 검증합니다. 확립된 마이그레이션을 통해 앵커 없는 더 안전한 URL을 사용할 수 있는 경우가 아니라면, 목적지를 확인할 수 없을 때 변경을 차단합니다. - 누락된 자산의 참조를 변경하기 전에 보이는 소스 폴더뿐 아니라 프레임워크의 가상 파일 시스템과 종속 항목이 제공하는 자산도 확인합니다. ## 프로젝트가 정한 용어로 짧고 직접적인 문장 쓰기 - 직접적이고 간결한 능동형 문장으로 작성합니다. - 모호한 완곡어, 홍보성 채움 문구, 글 자체를 논하는 메타 설명, 작업을 아무 노력 없이 할 수 있다고 묘사하는 표현을 제거합니다. - 독자를 중심으로 한 지침을 우선하며, 소유 주체를 명확히 해야 할 때는 제품이나 시스템의 이름을 밝힙니다. - 저장소에서 승인한 용어, 대소문자 표기, UI 작업 동사, 강조 규칙을 사용합니다. - 동작이 도입된 시점을 설명하는 영구적인 버전 도입 안내는 유지하고, 시간이 지나면 의미가 달라지는 상대적 표현은 피합니다. - 정당한 기술 용어는 적용 범위가 가장 좁은 어휘 허용 목록에 추가합니다. 표준 대소문자 표기를 사용하고, 관련 없는 검사까지 억제하는 광범위한 패턴은 피합니다. ## 페이지마다 제목과 설명을 넣고 구성요소를 바르게 쓰기 - 페이지 제목, 미리보기 설명, 검색 키워드 등 모든 필수 메타데이터 필드를 포함합니다. - 내비게이션 레이블은 문서에 정의된 한도 안에 두고, 섹션에서 필요할 때만 정렬 필드를 사용합니다. - 프레임워크 쇼트코드나 임베디드 구성요소를 작성하기 전에 구성요소 참조 문서를 확인합니다. 잘못된 구문은 오류를 드러내지 않은 채 실패하면서 손상된 결과를 만들 수 있습니다. - 클라이언트 측 UI 지시자의 문서화된 동작을 따릅니다. 한 숨김 방식이 다른 방식을 영구적으로 덮어쓸 수 있다면 두 방식을 함께 사용하지 말고, 프레임워크의 초기화 전 클로킹 방식을 사용합니다. - 로컬 빌드나 작업 트리의 제한을 우회하려는 목적으로만 전역 설정을 변경하지 마세요. ## 바뀐 파일부터 서식 정리와 검사를 하고, 필요하면 사이트 전체 확인하기 - 편집 후 변경된 파일에 저장소에서 제공하는 포매터를 실행합니다. - 더 광범위한 검증에 앞서 마크업과 본문을 함께 검사하는 파일 범위 린터를 실행합니다. - 증분 작업에서는 관련 없는 실패가 결과를 가리지 않도록 대상이 명확한 검사를 우선합니다. - 변경이 라우팅, 공유 구성요소, 내비게이션, 생성된 참조 문서 또는 그 밖의 페이지 간 동작에 영향을 주면 전체 사이트 빌드와 링크 검사를 실행합니다. - 통합 검증 대상이 환경과 호환되지 않는 경우 지원되는 검사를 개별적으로 실행하고 설정은 변경하지 않습니다. - 별도의 알림을 기다리지 말고 적용 가능한 검증을 완료하며, 실행할 수 없었던 검사가 있으면 보고합니다. ## 문제 하나에 작은 변경 하나로 고치고, 검토 의견마다 답하기 - 하나의 문제에는 초점을 맞춘 하나의 변경 세트만 만듭니다. 주변 정리나 관련 없는 리팩터링을 문서 수정에 섞지 마세요. - 파일을 명시적으로 스테이징합니다. 잠금 파일이나 생성된 변경사항까지 포함할 수 있는 광범위한 스테이징 명령은 절대 사용하지 마세요. - 커밋하기 전에 스테이징된 파일 목록을 확인하고, 의도한 문서 범위를 벗어난 항목은 제외합니다. - 모든 푸시 대상이 기여자의 포크 또는 승인된 다른 원격 저장소인지 확인하고, 보호된 상위 저장소로 푸시하지 마세요. - 문제 보고서와 검토 제안은 검증해야 할 주장으로 취급합니다. 문서를 변경하기 전에 실제로 관찰된 동작을 확인합니다. - 검토 의견을 반영한 뒤에는 별도의 검토 API 호출이 필요할 수 있는 줄 단위 댓글을 포함하여 모든 검토 스레드에 답변합니다. - 편의 명령이 신뢰할 수 없다면 레이블과 메타데이터를 보존하는 것으로 검증된 서비스 엔드포인트를 사용합니다. ## 페이지를 지우거나 새 버전을 더할 때 깨진 링크 남기지 않기 - 페이지를 삭제하기 전에 작성된 콘텐츠와 내비게이션 설정에서 해당 페이지의 슬러그, 제목, 별칭, 들어오는 참조를 검색합니다. - 버전이 지정된 참조 문서를 새 버전으로 올릴 때는 중앙 버전 설정 업데이트, 새 버전 페이지 생성, 이전 페이지의 최신 버전 별칭 이전을 하나의 변경으로 수행합니다. - 두 버전 페이지가 동일한 최신 버전 별칭을 동시에 사용하게 두지 마세요. - 생성된 참조 문서는 상위 사양이나 생성기를 변경한 뒤 결과를 다시 생성하고, 생성된 페이지를 직접 편집하지 마세요. - 수정 범위를 최소화하고 실제 실패를 검증하며, 소유 주체나 외부 근거가 확인되지 않은 경우 명확한 상위 보고 경로를 유지합니다.