파일이 많은 폴더에서 에이전트가 헤매지 않게 하는 법

파일이 몇백 개인 폴더를 열고 "버그 찾아 줘"라고 하면 결과가 좋지 않습니다. 에이전트가 게으른 것이 아니라, 볼 수 있는 양이 정해져 있어서 그렇습니다. 그 구조를 알면 큰 폴더에서도 정확하게 일하게 만들 수 있습니다.

창을 무엇이 차지하는가

한 번의 작업에서 다룰 수 있는 총량이 있습니다. 그 안에 이것들이 함께 들어갑니다.

• 지시문과 지금까지의 대화
• 폴더 구조(어떤 파일이 있는지)
• 읽은 파일의 내용
• 앞으로 만들 답변을 위한 여유분

이 중 가장 크게 차지하는 것이 파일 내용입니다. 그래서 파일을 무작정 많이 읽으면 정작 작업할 여유가 사라집니다.

파일은 한 번에 다 읽히지 않는다

파일 하나를 읽을 때 한 번에 가져오는 양에 상한이 있습니다(약 24,000자). 긴 파일은 잘려서 옵니다. 이때 "이어서 보려면 몇 번째 줄부터"라는 안내가 붙고, 에이전트는 필요하면 이어 읽습니다.

이 상한이 있는 이유는 단순합니다. 상한을 없애면 큰 파일 하나가 창을 통째로 먹습니다. 그러면 그 파일 말고는 아무것도 못 보는 상태가 됩니다.

사용자 입장에서 알아 두면 좋은 것: 긴 파일에서 특정 부분을 고칠 때는 위치를 알려 주는 편이 빠릅니다. "3천 줄쯤에 있는 handleSubmit 함수"처럼요.

볼 필요 없는 폴더는 애초에 보지 않는다

node_modules, .git, dist, build, __pycache__, .venv 같은 폴더는 훑는 대상에서 빠집니다. 이런 폴더는 파일이 수만 개씩 되고, 내가 쓴 코드가 아니라 도구가 만든 결과물입니다.

그래서 "왜 내 라이브러리 코드를 못 보지?"라는 상황이 생길 수 있습니다. 의도된 동작입니다. 그 안을 봐야 한다면 해당 파일 경로를 직접 알려 주세요.

큰 폴더에서 잘 시키는 방법

1. 찾기부터 시킨다

"버그 찾아 줘"보다 "calculateTotal 이라는 문자열이 어디에 있는지 찾아 줘"가 훨씬 잘 작동합니다. 검색은 파일 전체를 읽지 않고 위치만 알려 주므로 창을 거의 쓰지 않습니다.

순서를 이렇게 잡으면 좋습니다.

1. 검색으로 위치를 특정한다
2. 그 파일만 읽는다
3. 고친다

2. 폴더를 좁게 연다

프로젝트 최상위 대신 작업할 하위 폴더를 엽니다. 훑을 대상이 줄어드는 만큼 실제 작업에 쓸 여유가 늘어납니다.

3. 한 번에 한 가지만 시킨다

"로그인 고치고 회원가입도 정리하고 테스트도 추가해 줘"는 세 작업입니다. 나눠서 시키면 각 작업이 창 전체를 쓸 수 있습니다.

4. 파일 목록을 먼저 확인한다

/files 로 무엇이 잡히는지 볼 수 있습니다. 예상과 다르면(빠져야 할 폴더가 잡혔거나, 있어야 할 파일이 없거나) 그것을 먼저 해결하는 편이 빠릅니다.

수정이 실패하는 흔한 이유

파일 일부를 바꿀 때는 "바꿀 대상 문자열"과 "새 문자열"을 씁니다. 이때 두 가지로 실패합니다.

• 일치하는 곳이 없다 — 공백이나 줄바꿈이 미묘하게 다른 경우입니다. 에이전트가 파일을 다시 읽고 맞춰서 재시도합니다.
• 일치하는 곳이 여러 곳이다 — 어디를 고칠지 정할 수 없으니 거절됩니다. 앞뒤 문맥을 더 넣어 한 곳만 가리키게 해야 합니다.

두 번째가 특히 자주 납니다. return null 처럼 흔한 코드는 한 파일에 여러 번 나오기 때문입니다. 이럴 때는 함수 이름과 함께 지시하면 해결됩니다 — "getUser 안의 return null 을 고쳐 줘".

정리

• 창은 하나이고, 파일 내용이 가장 많이 차지한다.
• 파일은 한 번에 24,000자까지 읽힌다. 긴 파일은 이어 읽는다.
• 도구가 만든 폴더는 훑지 않는다.
• 검색 → 읽기 → 수정 순서가 큰 폴더에서 가장 잘 작동한다.
• 흔한 코드를 고칠 때는 함수 이름을 함께 말한다.