이 글은 이런 분께
- 몇 주 뒤에 자기 코드를 다시 열어보고 “이거 왜 이렇게 만들었더라?” 했던 경험이 있는 분
- 방문자에게는 안 보이면서 개발자한테만 보이는 메모를 남기는 방법이 궁금한 분
Before — “왜 이렇게 만들었는지”는 코드만 봐서는 안 보인다
프로젝트 페이지와 README에 방문자용 이용 안내를 두 군데 넣고 나니(→ 방문자 안내를 어디에 넣을지 헷갈렸던 이야기), 이런 부탁을 했다.
나중에 내가 이걸 다시 열었을 때 헷갈리지 않게 메모를 남겨줘.
- 어디를 고치면 뭐가 바뀌는지
- 왜 이렇게 만들었는지 (다른 방법을 두고 이걸 고른 이유)
- 하다 만 것 / 다음에 할 것
지금은 왜 두 군데(프로젝트 페이지 + README)에 비슷한 내용을 넣었는지, 왜 GPT 빌더 안쪽은 손 안 댔는지가 다 기억나지만, 몇 주 뒤에 이 파일을 다시 열면 코드만 봐서는 그 이유가 안 보인다. 결정 배경은 코드가 아니라 그때의 대화에만 남아 있었다.
어떻게 — 화면엔 안 보이는 HTML 주석을 골랐다
일반 마크다운 텍스트로 남기면 사이트에 그대로 노출돼서 방문자(채용담당자)가 보게 된다. 그래서 <!-- -->로 감싸는 HTML 주석을 썼다. 이렇게 감싼 내용은 브라우저가 화면에 그리지 않지만, 파일을 직접 열면 그대로 보인다.
<!--
개발 메모 (2026-08-12, 방문자용 이용 안내 추가) — 사이트에는 안 보이는 코멘트예요.
어디를 고치면 뭐가 바뀌는지
- 이 파일의 "## 처음 오셨다면 (이용 안내)" 섹션 = 프로젝트 상세 페이지에 보이는 방문자용 설명
- README.md 맨 위 "## 이 프로젝트는 뭘 만들었나요?" = GitHub 저장소에서 보이는 같은 내용(축약판)
...
-->
프로젝트 파일(edu-ai-toolkit.md) 맨 위에 이 메모를 넣고, README에는 “이 섹션을 왜 넣었는지는 프로젝트 파일 맨 위 메모 참고”라고 짧은 포인터만 남겼다. 메모를 두 번 쓰지 않고, 한 곳에만 자세히 두고 나머지는 링크만 거는 방식이었다.
확인 — 정말 안 보이는지 로컬로 띄워서 봄
주석이니까 당연히 안 보일 거라고 넘겨짚지 않고, 로컬 서버를 띄워서 실제 페이지 내용을 확인했다. 메모 텍스트가 화면에 전혀 안 나오는 걸 확인하고 나서야 커밋했다.
After — 3단 메모가 파일 안에 남았다
| 항목 | 내용 |
|---|---|
| 어디를 고치면 뭐가 바뀌는지 | 프로젝트 페이지 안내 / README 안내 / GPT 링크(frontmatter) / 버튼 문구(코드) 각각 어디 있는지 정리 |
| 왜 이렇게 만들었는지 | 두 군데에 넣은 이유(방문 경로가 둘이라서), GPT 빌더 안은 로그인이 필요해 AI가 못 건드린다는 이유 |
| 하다 만 것 / 다음에 할 것 | GPT 빌더의 대화 시작 문구는 아직 미정, 실제 GPT 대화 체험은 애진님 몫으로 남음 |
배운 것 / 재사용 자산
HTML 주석은 “방문자에겐 숨기고, 파일 열면 보이는” 메모에 딱 맞는다. 별도 문서를 만들면 나중에 안 찾아보게 되는데, 코드 바로 위에 있으면 그 파일을 열 때마다 자연스럽게 눈에 들어온다.
메모는 세 칸으로 나누면 충분하다. “어디를 고치면 뭐가 바뀌는지 / 왜 이렇게 만들었는지 / 하다 만 것”만 있어도, 몇 주 뒤의 나에게는 충분한 실마리가 된다.
재사용 패턴
<!--
개발 메모 (날짜, 무슨 작업)
어디를 고치면 뭐가 바뀌는지
- ...
왜 이렇게 만들었는지
- ...
하다 만 것 / 다음에 할 것
- ...
-->