Claude Code, Codex, Gemini CLI 같은 AI 도구와 연동해 문서를 교정하거나 내용을 추가할 때 참고해야 할 작성 기준과 주의사항을 설명합니다.
스타일 가이드를 읽도록 해서 이 내용을 AI 도구에게 숙지시킬 수 있습니다.
기본 원칙
AI 도구와 연동할 때는 문서의 의미뿐만 아니라 구조도 함께 유지해야 합니다. 특히 매뉴얼웍스 문서는 일반 마크다운 문서와 달리 마크다운과 HTML을 함께 사용하므로, 텍스트만 보고 수정하면 구조가 깨질 수 있습니다.
다음 사항을 기본 원칙으로 삼습니다.
텍스트는 교정할 수 있지만 HTML 태그와 링크 구조는 임의로 바꾸지 않습니다.
코드, XML, HTML 예제는 의미를 바꾸지 않는 범위에서만 수정합니다.
<,>,&같은 이스케이프 문자열은 원형을 유지합니다.매뉴얼웍스 전용 링크와 참조 마크업은 그대로 유지합니다.
문서 형식 이해하기
매뉴얼웍스 문서는 일반적인 마크다운 문서와 다릅니다. 제목, 목록, 인용은 마크다운으로 작성할 수 있지만, 표와 링크, 일부 서식은 HTML로 작성합니다.
예를 들어 다음 요소는 일반 마크다운이 아니라 HTML로 유지해야 합니다.
<a class="reference">형태의 상호 참조 링크<a class="link">형태의 웹 링크<table>태그로 작성한 표<code>,<strong>,<small>등의 인라인 태그
따라서 AI 도구에 교정이나 내용 추가를 요청할 때는 문서가 마크다운과 HTML을 함께 사용하는 형식이라는 점을 알려주면 좋습니다.
교정할 때 주의할 점
교정은 주로 오탈자, 띄어쓰기, 조사, 문장 흐름을 다듬는 범위에서 진행합니다. 다음 사항은 특히 주의해야 합니다.
HTML 태그의 이름과 속성은 바꾸지 않습니다.
참조 링크의
href와class속성은 바꾸지 않습니다.코드 블록과 XML 예제의 값은 근거 없이 수정하지 않습니다.
표는 마크다운 표로 바꾸지 않고 HTML 표를 유지합니다.
문장 교정 과정에서 태그 바깥의 조사나 띄어쓰기가 깨지지 않도록 주의합니다.
예를 들어 다음과 같이 요청하면 안전합니다.
HTML 태그, 링크, 코드, 이스케이프 문자열은 변경하지 말고 텍스트만 교정해줘.
내용을 추가할 때 주의할 점
새로운 내용을 추가할 때는 추가 위치와 작성 형식을 분명하게 지정해야 합니다.
내용은 단락 아이디를 기준으로 앞이나 뒤에 추가합니다.
내용은 마크다운 형식으로 작성합니다. 제목, 목록, 표, 강조, 링크 등을 사용할 수 있습니다.
문자 유형과 표도 마크다운으로 작성할 수 있습니다.
단, 매뉴얼웍스 전용 참조 링크나 특수한 HTML 구조는 추가한 뒤 결과를 확인합니다.
예를 들어 제목과 목록, 표를 추가할 때는 다음과 같이 요청할 수 있습니다.
다음 단락 다음에 내용을 추가해줘. [단락 아이디]
요청 예시
바로 수정하지 말고 교정할 부분만 알려줘.
HTML 태그, 링크, 코드, 이스케이프 문자열은 변경하지 말고 텍스트만 교정해줘.
AI 도구에 함께 알려주면 좋은 규칙
AI 도구와 연동할 때는 다음 규칙도 함께 전달하면 좋습니다. 특히 문자 유형, UI 이름, 찾아보기, 그림 단락과 교정 단락의 활용 방식은 미리 알려두면 일관된 결과를 얻는 데 도움이 됩니다.
매뉴얼웍스 문서 형식을 유지합니다.
HTML 태그와 링크 구조는 변경하지 않습니다.
이스케이프 문자열은 원형을 유지합니다.
텍스트 교정이 필요한 경우에만 문장을 수정합니다.
필요한 경우 단락 아이디를 기준으로 내용을 추가하거나 수정합니다.
문자 유형을 사용할 때 주의할 점
문자 유형은 필요한 경우에만 사용합니다. 불필요하게 많이 사용하면 문서가 복잡해지고 의미가 흐려질 수 있습니다.
<strong>는 반드시 강조해야 하는 핵심 내용에만 사용합니다.<code>는 명령어, 파일 이름, 설정 키, 실제 입력값처럼 그대로 구분해서 보여줘야 하는 내용에 사용합니다.<small>은 부가 설명이나 약칭 설명처럼 본문보다 가볍게 보여줄 내용에 사용합니다.기존 문자 유형이 이미 적용된 경우에는 의미를 바꾸지 않는 범위에서만 수정합니다.
찾아보기를 설정할 때 주의할 점
찾아보기를 설정할 때는 본문과 찾아보기 용어를 함께 작성합니다. 찾아보기는 검색에 도움이 되는 핵심 용어만 선택해 설정합니다.
찾아보기는
<span class="mark index">찾아보기 용어</span>형식으로 작성합니다.보통은 용어가 처음 나오는 위치에만 설정합니다.
같은 단락에 너무 많은 찾아보기를 넣지 않습니다.
검색어로 사용할 가치가 낮은 일반 표현에는 설정하지 않습니다.
확인 방법
AI 도구로 변경한 내용은 반드시 다시 확인합니다.
단락 내용이 의도대로 바뀌었는지 확인합니다.
HTML 태그와 참조 링크가 깨지지 않았는지 확인합니다.
예제 코드와 XML이 원래 의미를 유지하는지 확인합니다.
변경 내용은 매뉴얼웍스의 이력 기능으로 확인합니다.