노트 앱은 지휘본부로만 씁니다. 사실 판정은 저장소와 실제 소스가 합니다.
개발 기록이 세 군데로 흩어지면 어느 것이 맞는지 매번 다시 확인하게 됩니다. 로컬 소스에는 최신 코드가 있고, 저장소에는 승인과 결정이 있고, 노트 앱에는 요약이 있습니다. 셋이 어긋나면 사람이 판단해야 하는데, 판단할 근거가 또 그 세 군데에 있습니다. 그래서 역할부터 나눴습니다. 로컬 소스와 버전 관리는 실제 코드와 정상 실행의 기준, 저장소는 승인과 결정과 개발 기록과 테스트와 배포본의 공식 기준, 노트 앱은 프로젝트 연결과 상태 요약과 검색과 다음 행동과 인수인계를 맡습니다. 노트 앱의 요약이 저장소나 실제 소스와 충돌하면, 요약을 사실로 보지 않고 원본을 다시 확인합니다.
요약을 사실로 쓰면 생기는 일
노트 앱에 정리한 요약은 읽기 편합니다. 프로젝트 상태가 한 줄로 보이고 다음에 할 일도 적혀 있습니다.
문제는 이 편함 때문에 원본을 안 열게 된다는 점입니다. 요약이 일주일 전 상태인데 오늘 상태처럼 읽힙니다.
그래서 규칙에 문장을 하나 넣었습니다. 노트 앱의 요약이 저장소나 실제 소스와 충돌하면 요약을 사실로 간주하지 않고, 원본과 실제 상태를 다시 확인한 뒤 충돌을 기록하고 바로잡는다는 것입니다.
요약을 없애자는 뜻이 아닙니다. 요약이 있어야 검색과 연결이 됩니다. 다만 판정 권한은 주지 않습니다.
AI 코딩 도구의 공식 문서도 비슷하게 선을 긋습니다. Claude Code 문서는 지침 파일(CLAUDE.md)과 자동 기억을 모두 '강제되는 설정이 아니라 맥락'으로 다루며, 지침이 구체적이고 짧을수록 더 일관되게 따른다고 안내합니다. 기록이 아무리 잘 정리돼 있어도 그것이 곧 사실의 증명은 아니라는 점에서, 요약에 판정 권한을 주지 않는 이 글의 규칙과 방향이 같습니다.
실제 코드와 실행 기준을 버전 관리에 두는 이유도 공식 문서에서 찾을 수 있습니다. Git 문서는 Git이 저장하는 모든 것에 체크섬을 붙여 두기 때문에, 파일이나 폴더의 내용이 바뀌면 Git이 그 사실을 알 수 있다고 설명합니다. 사람이 쓴 요약은 몰래 어긋날 수 있지만, 버전 관리 기록은 바뀐 흔적이 남습니다.
| 기준 | 맡는 것 |
|---|---|
| 로컬 소스·버전 관리 | 실제 코드와 정상 실행 |
| 저장소 | 승인·결정·개발 기록·테스트·배포본·백업 |
| 노트 앱 | 프로젝트 연결·상태 요약·검색·다음 행동·인수인계 |
| 충돌할 때 | 저장소와 실제 소스를 다시 확인 |
명령 네 개를 더했다
노트 앱을 붙이면서 시작 명령을 네 개 추가했습니다. 각각 하는 일이 겹치지 않게 범위를 정했습니다.
동기화 명령은 코드를 건드리지 않습니다. 저장소와 로컬과 버전 관리 상태를 확인해 노트 앱의 현황만 갱신합니다.
중간점검은 기능이나 오류나 테스트나 결정 중 하나가 끝났을 때 씁니다. 단순 명령 실행이나 사실 변화가 없는 확인만으로는 새 노트를 만들지 않습니다.
종료 체크포인트는 현재 단계의 저장소 기록과 노트 앱 인수인계를 함께 닫습니다. 주간 점검은 진행 중인 프로젝트 전체의 어긋남을 훑습니다.
| 명령 | 하는 일 | 안 하는 일 |
|---|---|---|
| 동기화 | 노트 앱 현황만 갱신 | 코드 수정 |
| 중간점검 | 끝난 작업 단위를 저장소에 고정 | 사실 변화 없는 노트 생성 |
| 종료 체크포인트 | 저장소 기록과 인수인계를 함께 닫음 | 저장 확인 없이 보고 |
| 주간 점검 | 전체 프로젝트의 어긋남 확인 | 확인 없이 최신 표시 |
저장 순서를 지킨다
단계가 끝나면 순서대로 저장합니다. 먼저 로컬 실행과 테스트 결과, 버전 관리 상태를 확인합니다.
그다음 저장소의 상태 문서와 개발 기록과 테스트 기록을 갱신합니다. 올린 파일은 다시 읽거나 내려받아 실제로 반영됐는지 확인합니다.
여기까지 끝난 뒤에야 노트 앱의 프로젝트 노트를 갱신합니다. 저장소 갱신과 재확인 없이 노트 앱만 최신으로 표시하지 않는다는 규칙이 있습니다.
마지막으로 기존 인수인계를 날짜가 붙은 보관본으로 남기고 현재 인수인계를 새로 씁니다. 그리고 다음 행동을 한 문장으로 고정합니다.
- 로컬 테스트와 버전 관리 상태 확인
- 저장소의 상태·개발·테스트 기록 갱신
- 올린 파일을 다시 읽어 반영 확인
- 노트 앱 프로젝트 노트 갱신
- 날짜별 인수인계 보관본 생성
- 현재 인수인계 갱신과 다음 행동 한 문장
물어보지 않고 해도 되는 것
기록을 남기는 일마다 승인을 받으면 기록이 밀립니다. 그래서 비파괴적인 갱신은 미리 허용 범위로 정해 뒀습니다.
프로젝트 현황 요약 갱신, 단계 체크포인트 생성, 날짜별 인수인계 보관본 생성, 현재 인수인계 갱신, 프로젝트 목록의 링크와 상태 갱신, 오류와 결정과 테스트 기록의 신규 파일 생성입니다.
반대로 매번 승인이 필요한 것도 적어 뒀습니다. 기능 범위 변경, 기존 승인 문서의 의미 변경, 파일 삭제나 영구 이동, 외부 공개와 발송, 결제와 권한 변경, 계정 로그인입니다.
기록은 늘리는 방향이고 되돌리기 어려운 일은 막는 방향입니다. 한 표에 적어 두니 매번 판단하지 않게 됐습니다.
| 승인 없이 | 매번 승인 |
|---|---|
| 현황 요약·상태 갱신 | 기능 범위 변경 |
| 단계 체크포인트 생성 | 승인 문서의 의미 변경 |
| 인수인계 보관본·갱신 | 파일 삭제·영구 이동 |
| 오류·결정·테스트 기록 생성 | 외부 공개·발송·결제 |
주간 점검에서 잡히는 것
마지막 점검일로부터 7일이 지난 뒤 처음 작업을 시작할 때 한 번 훑습니다. 앱이 꺼진 동안 알아서 돌 거라고 가정하지 않습니다.
진행 중으로 표시돼 있는데 7일 이상 확인되지 않은 프로젝트를 찾습니다. 대기와 보류 상태는 이유와 다음 확인일이 적혀 있는지 봅니다.
그리고 저장소와 로컬의 버전이 어긋난 곳, 반복해서 실패한 작업을 찾습니다. 반복 실패는 새 절차 문서를 만들 후보가 됩니다.
막히는 지점과 지키는 선
노트 저장 폴더가 여러 개일 때는 최근 수정일만으로 고르지 않습니다. 파일명이나 시각으로 추정하면 엉뚱한 폴더에 기록을 쌓게 됩니다. 후보가 여러 개면 한 번만 물어봅니다.
저장소 연결이 실패하면 오류 원문을 그대로 보존하고, 올리지 못한 사본을 로컬에 만들어 둡니다. 단순한 파일 작업 때문에 브라우저를 열어 자동화하지는 않습니다.
공식 문서를 고칠 권한이 없으면 초안 폴더에 반영안을 만들고 위치를 보고합니다. 권한이 없다고 작업을 멈추지도, 우회해서 고치지도 않습니다.
기록에 남기지 않는 것도 정해 뒀습니다. 비밀번호, 접근 키, 쿠키, 인증 코드, 개인 키, 그리고 필요 없는 개인정보입니다. 대신 별칭이나 사용 가능 여부 같은 최소 정보만 남깁니다.
자주 묻는 질문
Q. 노트 앱 요약을 믿으면 안 되나요?
A. 요약은 검색과 연결에 쓰고 판정에는 쓰지 않습니다. 저장소나 실제 소스와 어긋나면 원본을 다시 확인한 뒤 요약을 고칩니다.
Q. 갱신은 어떤 순서로 하나요?
A. 로컬 테스트와 버전 상태 확인, 저장소 기록 갱신, 반영 재확인, 노트 앱 갱신, 인수인계 보관 순입니다.
Q. 매번 승인을 받아야 하나요?
A. 기록을 남기는 비파괴적 갱신은 미리 허용 범위로 정해 뒀습니다. 기능 범위 변경, 삭제, 외부 공개, 결제, 로그인만 매번 승인을 받습니다.
Q. 주간 점검은 자동으로 도나요?
A. 앱이 꺼진 동안 배경에서 도는 것으로 가정하지 않습니다. 마지막 점검일로부터 7일이 지난 뒤 처음 작업을 시작할 때 한 번 수행합니다.
확인 자료
- 개발 기록 연동 부록 v1.1 — 역할 분리, 추가 명령, 갱신 시점, 승인 범위 (확인 2026-09-09)
- 개발 에이전트 운영 지침 v1.1 — 저장 순서, 주간 점검 항목, 보안 기록 금지 항목 (확인 2026-09-09)
- 개발 기록 동기화 규칙 문서 v1.1 — 막히는 지점과 대응 (확인 2026-09-09)
- Claude Code 공식 문서 · How Claude remembers your project (2026-10-18 기준)
- Git 공식 문서 · What is Git? (2026-10-18 기준)
이 글은 직접 겪은 작업 기록을 정리한 것입니다. 확인하지 못한 항목은 본문에 쓰지 않았습니다. 대표 이미지는 이해를 돕기 위한 참고용 이미지입니다.