[태그:] 프로젝트 문서

어제 AI와 만든 재고 앱에 오늘 ‘재고 부족만 보기’를 추가한다고 상상해 보자. 새 대화창에 프로젝트 폴더를 건네면 AI는 실행법과 데이터의 뜻을 알아내고, 기존 저장 기능을 지키면서 수정할 수 있을까?

이 질문을 확인할 비교 자료와 검사 도구를 준비했지만, AI가 앱을 이어서 수정하는 측정 실행은 한 번도 하지 않았다(NOT RUN). AI가 제공 자료 밖의 이전 기록·메모·파일을 읽지 못하는지 확인하는 격리 시험과 사용량·추가 과금 확인이 남아 있었다. 10월 26일 기록에는 Claude 명령줄 도구(CLI)가 로그아웃 상태였다고 남아 있으며, 이번 원고 작업에서 로그인 상태를 다시 확인하지 않았다. 총괄은 2026년 11월 5일 방법론 글로 범위를 정했다. 따라서 답은 아직 모른다. 여기서는 무엇을 남기고 확인할지, 비교를 어떻게 설계했는지, 준비에서 확인한 것과 측정을 멈춘 이유를 설명한다.

측정 전 멈춘 비교 설계와 확인 방법 — 성능 결과는 아직 없다.

대화 대신 넘길 기록은 무엇일까?

GitHub의 README 안내는 프로젝트를 시작하는 데 필요한 정보를 문서에 담도록 권한다. AGENTS.md 역시 AI 에이전트용 실행·검사 지침을 담는 파일 관례다. 둘 다 이번 앱에서 문서가 성과를 높였다는 증거는 아니다. 아래 설명은 2026년 10월 8일 확인한 공개 문서를 바탕으로 한다. GitHub README 안내, AGENTS.md 안내

독자가 적용해 볼 제안은 실행법, 데이터의 뜻, 확인할 동작, 알려진 한계를 짧게 남기는 것이다. 여기에 이번 요청과 확인 날짜를 덧붙인 여섯 줄은 검증된 최소 항목이나 효과가 입증된 양식이 아니라 편집상 제안이다. 뒤에서 설명할 P 조건의 문서 네 개와는 다른 독자용 양식이며, 계획한 실험의 투입 자료가 아니다. README·AGENTS.md 관례 자체도 이번 비교의 대상이 아니다.

실행: 어느 폴더에서 어떤 명령을 쓰는가? 정상 화면은 무엇인가?
데이터: 어디에 저장되며, 각 항목과 계산 규칙은 무슨 뜻인가?
확인: 변경 전후에 반복할 동작과 기대 결과는 무엇인가?
한계: 확인한 사용 범위와 아직 확인하지 못한 것은 무엇인가?
이번 요청: 바꿀 동작과 반드시 유지할 동작은 무엇인가?
확인 날짜: 이 기록을 실제 파일·실행 결과와 대조한 때는 언제인가?

옛 대화 전체를 옮길 필요는 없다. 넘길 폴더와 기록에는 비밀번호·비밀 정보나 이전 대화 내보내기 파일을 넣지 말자. 기록의 명령과 규칙은 실제 파일에 맞는지 대조하고, 모르는 것은 모른다고 남기는 편을 제안한다. 오래된 문서가 어떤 영향을 주는지는 계획한 비교에 포함하지 않았다.

새 대화가 곧 이전 정보가 없는 환경이라는 뜻도 아니다. 조사 당시 Claude 문서에는 프로젝트 지침과 자동 메모리를 읽는 경로가 설명되어 있었다. 이 문서 설명과 별개로, 이번 설계에서는 폴더나 세션 이름만으로 격리를 판정하지 않고 실제 환경의 파일·저장 정보 접근을 따로 확인하도록 했다. Claude 메모리 문서

같은 앱에 설명 파일만 더하는 비교

합성 데이터만으로 준비한 것은 개인용 로컬 재고 앱 두 변형이다. A는 작업실 물품, B는 공방 부품이며 각각 가상 항목 12개를 가진다. 항목명과 데이터 필드 이름은 다르지만 수량과 규칙은 같다. 둘 다 ‘보유 수량 − 예약 수량’이 재고 부족 판정 기준보다 작을 때만 재고 부족이다. 기준과 같으면 부족이 아니고, 사용 중지 항목도 제외한다.

P의 파일명은 START-HERE.md, DATA-DICTIONARY.md, ACCEPTANCE.md, KNOWN-LIMITS.md다. 자동 지침 대신 AI가 열어 볼 일반 문서로 설계했다. 실제 자동 로딩 여부는 미실행 사전 시험으로 확인할 대상이었다. 두 조건 모두 같은 변경 요청과 프로젝트 파일 안의 명령 목록을 받으므로 ‘맨 코드와 친절한 설명’의 비교가 아니다. P의 문서는 C에도 있는 명령을 되풀이하고, 코드의 규칙을 문장으로 풀어 쓴다. 시작 명령은 요청문이 아니라 프로젝트 파일에서 찾아 쓰도록 했다. 파일을 제공했다는 사실과 AI가 읽고 활용했다는 사실도 구별해야 한다.

영어로 작성한 공통 요청은 기존 재고 부족 표시 규칙을 재사용해 ‘전체 / 재고 부족만’ 필터를 추가하는 것이었다. 전체 보기가 기본이어야 하고, 필터를 꺼도 원래 순서와 항목이 돌아와야 한다. 조회만으로 저장 파일이 바뀌면 안 된다. 수량 수정, 잘못된 입력 거부, 저장 후 재시작해도 값이 남는 동작을 유지해야 한다. 화면 구조와 수정 가능 파일도 제한했으므로 자유로운 앱 개발 비교는 아니다.

실행 순서는 A-C → A-P → B-P → B-C, 총 네 번으로 계획했다. 같은 모델과 설정을 쓰되 매번 새 세션과 원본 복사본을 주고, A에서는 C가, B에서는 P가 먼저 오도록 한 것이다. 다만 A가 항상 B보다 먼저이고 두 변형의 규칙도 같으므로, 이 순서만으로 앞선 실행이나 서비스 내부 상태의 영향을 제거했다고 할 수 없다. 그러나 네 번을 마쳤더라도 같은 틀의 앱 두 개, 영어 요청, 한 모델을 보는 작은 사례 비교다. 다른 제품의 AI, 사람에게 넘기기, 미래의 내가 다시 쓰기, 한국어 지시 성능까지 설명할 수 없다. 이번에는 그 네 번 모두 미실행이다.

‘알겠다’는 답보다 확인할 동작

먼저 변경 전에 앱이 열리는지 확인하고, 변경 후에는 새 기능과 기존 기능을 나누어 확인하도록 설계했다. 개정 설계의 엄격한 미만 규칙에 따른 기대 정답은 각 변형의 01·02·05·11·12번이다. AI가 만든 결과가 아니다. 정답 목록만 맞추는 편법을 걸러내려면 수량을 바꾼 뒤 목록도 바뀌는지, 기준과 같은 값은 제외되는지 확인해야 한다. 저장 파일의 변경 전후 비교와 전체 코드 변경 검토도 필요하다.

AI가 알아낸 사실은 실행 명령, 데이터 위치·구조, 가용 수량 계산, 부족 판정, 검사 명령, 사용 한계의 여섯 항목으로 기록하도록 계획했다. 앞의 다섯 항목은 양쪽 모두 파일에 명시되어 있거나 코드·검사에서 추론할 수 있고, 개인용이라는 명시적 설계 한계는 P에만 있다. 공통 명령을 보고 답한 것은 제공된 정보를 찾아 쓴 것이다. 맞는 답이라도 근거 파일을 잘못 대면 뒷받침된 답으로 보지 않되, 내용의 정확성과 근거의 적절성은 따로 남긴다. 실제 코드나 관련 검사가 근거가 될 수 있으며, 설명 문서가 있다는 이유만으로 그쪽을 정답으로 우선하지 않는다. 틀림, 모름, 답하지 않음을 구분한다. 특히 C에는 개인용이라는 명시적 설계 한계가 없고 P에는 있으므로, C에서 이를 모른다고 했다고 곧바로 오답으로 처리하면 불공정하다. 이 항목들을 단순 합산해 P의 우위로 읽어서는 안 된다. 질문이 없다고 이해한 것도 아니고, 필요한 질문을 했다고 실패한 것도 아니다. 사실 보고와 실제 기능 검사는 별개다.

시간을 비교하려면 AI의 응답 대기뿐 아니라 설명 파일 작성, 안전 검토, 외부 검사 시간을 따로 남겨야 한다. 이번에는 작업 속도나 절약 시간을 계산할 측정값이 없다. AI가 “완료했다”고 말한 것과 실제 화면·저장·변경 검사를 통과한 것도 별개다.

오프라인 준비에서 확인한 범위

AI 도구와 연결하는 부분과 실행·종료를 관리하는 부분을 따로 검사했다. 2026년 10월 17일 실행 기록을 10월 26일 문서로 검토했으며, 재실행은 아니었다. 실제 모델을 호출하지 않은 연결 도구 검사 23개와 실행 관리 도구 검사 21개는 결과 파일상 통과였다. 앱 검사기는 22개 사례에서 미리 정한 통과·실패 결과와 일치했다. 여기에는 잘못된 구현을 거부하는 검사도 있으므로 ‘앱 22개 성공’이라는 뜻이 아니다. 두 조건의 공통 파일 내용이 같다는 점도 확인했다. 공통 파일의 일치만으로 P의 설명 문서 네 개까지 모두 정확하다고 판정할 수는 없다. 이 글은 네 문서를 하나씩 대조한 완전한 검증 결과를 제시하지 않는다.

별도로 브라우저에서 원본과 준비자가 만든 정답 구현을 확인한 기록을 검토했다. 기록상 목록·입력 거부·저장·재시작과 정답 구현의 필터를 포함한 16개 점검 항목이 통과했다. 원본에는 새 필터가 없으며 필터 동작 점검은 정답 구현을 대상으로 했다. 이는 준비 과정 안에서 시험 자료와 검사 도구를 맞춰 본 결과이며, 독립적인 성능 검증이 아니다. 새 AI 세션이 만든 수정본의 성적이 아니다. 브라우저 조작도 준비 검증을 맡은 에이전트가 수행했으며, 실제 사람이 앱을 인수한 사례가 아니다.

기록에는 한계도 있다. 연결 도구·실행 관리 도구·앱 검사 단계는 프로그램의 종료 상태를 나타내는 코드가 총괄 로그에 비어 있었다. 앞의 두 단계는 결과 파일에서 성공을 추론했고, 앱 검사 단계는 별도 결과 파일에 종료 코드가 남아 있었다. 브라우저의 배경 통신 구분에는 추론이 포함됐고, 컴퓨터 전체의 외부 통신을 관찰한 것은 아니다. 따라서 브라우저 검사 중 외부 통신이 전혀 없었다고도 단정할 수 없다. 이전에 기록한 것과 달라진 Python 실행 환경은 AI 모델을 쓰지 않은 이 검사 범위에서만 받아들였다. 실제 AI 실행 경로에 대한 승인은 아니다. 이런 준비 통과를 실제 AI의 격리나 전체 실행 준비 완료로 확대할 수 없다.

측정을 멈춘 이유와 남는 질문

실제 측정 전에 작은 사전 시험이 필요했다. 허용 폴더 안의 파일은 읽고 고칠 수 있는지, 밖에 둔 무해한 표식 파일은 읽기가 거부되는지, 실행 요청과 결과 전달·종료가 실제 Claude CLI에서 이어지는지를 확인하려는 시험이다. 가짜 응답으로 도구를 검사한 결과는 이 실제 경로의 증거를 대신하지 못한다. 성공했더라도 서비스 내부 상태나 캐시가 모두 지워졌다는 증명은 아니다.

10월 26일 기록에서 Claude CLI는 로그아웃 상태였다. 작업 에이전트가 임의로 로그인하거나 재인증하지 않는 운영 경계 때문에 사전 시험을 시작하지 않았다. 당시에도 구독 잔여 사용량과 추가 과금 없는 경로의 근거, 실제 격리 시험, 그 기록의 독립 검토도 남았다. 전체 사전 시험 프로그램을 감싸는 강제 시간 제한 장치가 없다는 한계도 해결된 것으로 볼 수 없었다. 11월 5일 결정은 이 상태를 성능 결과로 포장하지 않고 방법론 글로 전환한 것이다.

따라서 설명 파일이 더 빠른지, 수정 성공을 높이는지, 어느 조건이 낫는지는 답할 수 없다. 차이가 없거나 설명이 오히려 방해하는 가능성도 열려 있다.

내 앱에 적용해 볼 확인 순서 — 효과 미검증 제안

1. 위 양식의 기록을 실제 앱과 대조하고, 모르는 내용은 표시한다.
2. 변경 전에 앱을 열어 보고, 유지할 화면·입력·저장 동작을 정한다.
3. 변경 후 새 기능과 기존 기능을 따로 확인한다. 재고 예에서는 수량을 바꿔 목록이 바뀌는지, 기준과 같은 값이 제외되는지도 본다.
4. 저장 파일과 코드의 변경을 확인하고, AI의 완료 설명과 실제 실행 결과를 구분한다.

이 순서와 위 양식은 적용해 볼 제안이며, 이번 준비가 효과를 입증한 방법은 아니다.

이 글은 AI를 활용해 자료 조사와 초안 작성을 보조했으며, 작성자가 최종 원고를 검토하고 수정 방향을 결정했습니다.