AI 초안의 Markdown 코드블록 검수: 울타리·언어 이름·실행 결과를 나누기
코드블록이 예쁘게 보인다는 사실과 코드가 올바르게 실행된다는 사실은 다릅니다. AI가 만든 Markdown 초안을 옮길 때는 먼저 시작·끝 울타리가 의도한 범위를 감싸는지 확인하고, 그다음 표시와 실제 검증을 구분하세요.
① 백틱 울타리의 시작·끝 ② 선택한 언어 이름 ③ 옮긴 곳의 미리보기. 문법 강조 색상만 보고 실행 성공으로 기록하지 않습니다.
1. 울타리는 표시할 범위를 감쌉니다
GitHub Docs는 코드블록 앞뒤에 백틱 세 개를 놓는 fenced code block 문법을 설명하며, 원문을 읽기 쉽도록 앞뒤에 빈 줄을 둘 것을 권합니다. 코드블록 안에 백틱 세 개를 그대로 보여 주려면 바깥쪽을 백틱 네 개로 감싸는 예시도 제공합니다. GitHub 코드블록 공식 문법을 참고하세요.
이 문법 설명은 GitHub 웹의 Markdown 사용을 기준으로 합니다. 다른 블로그 편집기나 문서 도구가 같은 원문을 반드시 똑같이 표시한다고 가정하지 않고, 실제 붙여 넣을 곳에서 미리보기를 확인합니다.
2. 짧은 원본으로 설명문까지 묶이지 않았는지 보기
다음은 직접 만든 검수용 예시입니다. 실행을 지시하거나 결과를 확인한 예제가 아니라, 코드와 설명의 경계를 읽는 연습입니다.
```python
message = "검토용 예시"
print(message)
```
이 문장은 코드블록 밖의 설명입니다.끝의 백틱 뒤에 있는 “이 문장은 코드블록 밖의 설명입니다”가 미리보기에서 별도 문단으로 보이는지 확인합니다. 설명문까지 코드 모양으로 묶이면 초안 원본의 끝 울타리 위치와 붙여 넣기 결과를 대조하세요.
문제가 생겼다고 전체 초안을 반복 덮어쓰기 전에 작은 예시로 범위를 줄여 보는 편이 좋습니다. 원본을 보존하고 바뀐 부분만 비교하면 삭제된 줄이나 빠진 설명문을 찾기 쉬워집니다.
3. 언어 이름과 실행 결과를 혼동하지 않기
GitHub 공식 문서는 선택적으로 언어 식별자를 붙여 문법 강조를 사용할 수 있다고 설명합니다. 강조는 소스의 색과 스타일을 바꿔 읽기 쉽게 하는 표시 기능입니다. 이 설명에서 코드의 기능이나 실행 성공을 보장하지는 않습니다.
| 검수 항목 | 확인하는 것 | 별도로 남길 것 |
|---|---|---|
| 울타리 | 의도한 줄만 코드블록에 포함되는지 | 누락·범위 오류 여부 |
| 언어 이름 | 코드의 언어와 의도한 표시 정보가 맞는지 | 대상 도구가 지원하는지 |
| 미리보기 | 코드와 설명이 읽기 좋게 나오는지 | 표시를 확인한 장소 |
| 실행 검증 | 필요한 경우 별도 환경에서 기능을 검증 | 실제로 한 검증과 아직 안 한 검증 |
AI 초안에 들어 있는 명령이나 코드를 단순히 표시를 확인하려고 실행할 필요는 없습니다. 특히 파일 삭제, 계정 접근, 결제, 외부 전송을 포함한 코드는 문서 서식 검수와 분리해 검토합니다.
4. 백틱 자체를 설명할 때의 작은 예시
Markdown 사용법을 독자에게 설명하는 초안에는 백틱이 설명 대상이 됩니다. 바깥 울타리와 안쪽 예시를 같은 길이로 쓰면 범위를 읽기 어려워질 수 있습니다. 다음 원문은 안쪽의 세 개 백틱을 보여 주기 위해 바깥을 네 개로 감싼 형태입니다.
````
```text
이 안의 백틱 세 개도 독자에게 보여 줍니다.
```
````원문 보기에서는 바깥쪽 네 개와 안쪽 세 개를 구분하고, 미리보기에서는 독자에게 보여 줄 안쪽 예시가 남는지 확인합니다. 이 방식은 백틱을 설명하는 글에 유용한 예시이며 모든 코드블록을 무조건 네 개로 바꾸라는 규칙은 아닙니다.
5. 게시 전 짧은 완료 메모
자체 검수 메모에는 “원본 보존 위치 / 확인한 미리보기 / 울타리 포함 범위 / 언어 이름 / 실행 검증 여부”를 적습니다. 실행하지 않았다면 “표시만 확인, 실행 미확인”이라고 남기면 됩니다. 확인하지 않은 항목을 완료로 채울 필요가 없습니다.
문법 강조가 안 보이면 코드가 틀린 건가요?
표시와 기능은 별개의 확인입니다. 대상 도구의 Markdown 지원과 언어 식별자를 먼저 확인하고, 코드 기능에 대한 결론은 별도 검증 근거로 판단합니다.
AI 답변 전체를 코드블록에 넣어도 되나요?
독자에게 원문을 그대로 보여 주려는 목적이라면 가능하지만, 일반 설명과 링크까지 묶이면 읽기 방식이 달라집니다. 독자가 읽을 설명과 원문 예시의 역할을 먼저 정하세요.
자료 확인: 2026년 10월 5일. 출처: GitHub Docs, Creating and highlighting code blocks. 본문의 짧은 코드와 검수 양식은 직접 만든 표시 확인 예시이며 실행 결과를 주장하지 않습니다.
대표 이미지는 AI로 제작한 주제 이미지이며, 본문 설명표 이미지는 별도로 구성했습니다.
댓글
댓글 쓰기