내 개발 노트를 체계화하기 시작한 이유 (지적받고 나서 😅)

Source: Dev.to

초기 소프트웨어 엔지니어 시절, 내 노트는 완전한 혼란 그 자체였다.
상사는 내 노트가 여기저기 흩어져 있다고 지적했고, 그녀의 말이 맞았다.

나는 어디에든 노트를 남겼다:

• 노트북
• 포스트잇
• 스크린샷
• 슬랙 메시지
• ChatGPT 대화

개발 중에 무언가를 해결하면 어디엔가 적어두었지만, “어디엔가”는 매번 같은 장소가 아니었다. 같은 문제가 다시 나타나면 모든 곳을 뒤져야 했고, 더 나빠서는 다시 상사에게 물어야 했다.

---

문제: 흩어진 노트

20년 이상의 경력을 가진 아키텍트이자 엔지니어, 솔루션 분석가인 내 상사는 채팅을 검색하거나 메시지를 스크롤해서 찾지 않았다. 대신 적절한 문서를 바로 열었다:

• FRS
• 기술 문서
• 시스템 노트

모든 것이 구조화되고 추적 가능했다. 시스템 흐름을 확인해야 할 때? 문서를 열면 된다. 요구사항을 확인해야 할 때? 문서를 열면 된다. 로직을 이해해야 할 때? 문서를 열면 된다. 그 과정은 손쉽게 보였고, 나는 놀라웠다.

더 나은 실천 관찰

다른 개발자들을 보면서 나는 Google Keep이라는 단순하지만 강력한 도구를 발견했다. 프로젝트 설정, 디버깅 단계, 설정, 유용한 명령어 등을 섹션별로 깔끔하게 기록할 수 있었고, 모두 검색이 가능했다.

진짜 문제는 잊어버리는 것이 아니라, 이미 배운 내용을 찾지 못한다는 것이었다.

나만의 구조화된 노트 시스템

작은 습관 하나를 바꾸었다: ChatGPT가 무언가를 해결해 주면(오류 디버깅, 프레임워크 이해, 설정 수정 등) 유용한 부분을 추출해 내 구조화된 노트에 저장했다.

예시 레이아웃

• 프로젝트 설정 – 환경 구성 및 설치 단계
• 공통 오류 – 오류 메시지, 원인, 해결책
• 디버깅 노트 – 깨진 부분과 해결 방법
• 아키텍처 이해 – 서비스 흐름 및 시스템 로직
• 데이터베이스 노트 – 중요한 테이블 및 쿼리
• 유용한 명령어 – 터미널 명령 및 스크립트

그 차이는 엄청났다. 며칠 혹은 몇 주 뒤에 프로젝트에 다시 돌아가면, 처음부터 시작하는 대신 내 노트를 검색하면 된다. 또한 “지난번에 어떻게 해결했지?” 같은 질문으로 상사를 방해하는 빈도도 줄어들었다. 노트를 정리하면서 나는 반복해서 같은 문제를 푸는 것이 아니라, 시간이 지나면서 지식을 쌓아가는 엔지니어가 된 느낌이었다.

좋은 개발자는 단순히 코드를 작성하지 않는다—배운 것을 기억하기 위한 시스템을 만든다. 성장의 시작은 종종 “너의 노트가 흩어져 있다”는 한 마디에서 비롯된다. 그 한 문장이 내 작업 방식을 조용히 바꾸어 놓았다.

도구 및 참고 자료

• Google Keep –
• Notion –
• Obsidian –

추가 읽을거리

• Functional Requirement Specification 설명 –
• 소프트웨어 문서 가이드 –

나는 아직도 문서화 방식을 개선하고 있다. 여러분은 개발 지식을 어떻게 정리하고 있나요? 노트 앱, 문서, 개인 위키, 혹은 다른 방법? 다른 개발자들의 노하우를 배우고 싶다.