← 제작기

도구가 보여 준 화면은 지금이 아니었다

10월 21일에 Claude Navigator 를 만들었습니다. ~/claude 아래 저장소 49곳마다 하는 일과 최근에 한 일, 그 일을 맡은 Claude 세션을 모아 "이 일은 어디에 물어보나"를 알려 주는 화면입니다. 같은 페이지 한 장이 비공개 아티팩트와 맥의 로컬 서버 두 곳에서 돌고, 화면 확인은 Claude 가 데스크톱 앱의 내장 브라우저로 했습니다.

이 저장소 문서의 함정 목록은 열여섯 줄입니다. 그 가운데 여럿은 코드의 잘못이 아니었습니다. 스크린샷과 콘솔, 시각처럼 확인에 쓴 도구가 보여 준 것을 지금의 사실로 읽을 뻔한 일이었고, 같은 주에 사이트 쪽 세션에서도 같은 일이 두 번 있었습니다. 그중 몇 개를 골라 적습니다.

가려진 창에서는 직원이 한 명도 보이지 않았다

10월 20일 새벽, Claude 빌딩 데모를 사이트에 넣기 전에 사이트의 보안 정책(CSP)을 붙인 사본에서 돌려 봤습니다. 빌딩은 세션을 직원으로 보여 주는 3D 사무실입니다. 원래 데모에서는 직원 6명이 보였는데, 사본에서는 건물만 그려지고 직원 0명에 활동 기록도 0줄이었습니다. 콘솔에는 오류가 없었습니다.

정책을 붙이자마자 직원이 사라졌으니 정책을 의심하는 것이 자연스러웠습니다. 정책에 막힐 만한 eval 류 코드를 찾아봤지만 없었고, 불러온 파일 11개는 모두 200 이었습니다. 페이지의 숨김 여부를 강제로 "보임"으로 바꾸고 4초를 기다려도 0명이었습니다. 원래 데모를 다시 열자 그쪽도 0명이 됐습니다. 페이지는 스스로 보이는 중(visible)이라고 답했지만, 브라우저의 탭 정보를 읽어 보니 내장 브라우저 창 자체가 가려져 있었습니다. 가려진 창에서는 화면을 다시 그리는 프레임(requestAnimationFrame)이 오지 않습니다. 스크린샷을 한 장 찍자 화면이 그려졌고, 3초 뒤 사본에서 직원 7명과 활동 기록 30줄이 보였습니다. 보안 정책은 처음부터 상관이 없었습니다.

다음 날 Navigator 에서 같은 것을 또 밟았습니다. 뇌 지도는 맥락 영역과 저장소 영역을 오갈 때 점들이 750밀리초 동안 새 자리로 옮겨 가는데, 미리보기 탭이 뒤에 있자 이 애니메이션이 멈춰 이름표 없는 중간 모습으로 남았습니다. 이번에는 페이지를 고쳤습니다. 화면이 숨어 있으면 움직임 없이 마지막 모습을 바로 그리고, 숨김 검사를 지나쳤더라도 1초가 지나면 프레임이 오든 말든 마무리합니다. 빌딩 때처럼 페이지가 보이는 중이라고 답하면 숨김 검사는 걸러 내지 못하고 1초 시한만 남는데, 가려진 창에서 그 시한이 실제로 도는지는 아직 재 보지 않았습니다. 미리보기에서 잰 것을 실서버에서 다시 잰 빌딩 이야기는 고친 화면을 다시 재 보니 다음 것이 보였다에 따로 적었습니다.

스크린샷과 콘솔은 조금 전을 보여 줬다

Navigator 의 자세히 보기 창은 열릴 때 누른 곳이 창에 가리지 않도록 페이지를 부드럽게 스크롤합니다. 그 도중에 찍은 스크린샷에는 창이 없었습니다. 코드로 물어보면 창은 열려 있었습니다. 사진과 코드가 엇갈리면 사진 쪽을 믿기 쉽습니다. 1초를 기다려 다시 찍자 창이 제자리에 있었고, 앞의 사진은 스크롤이 끝나기 전의 화면이었습니다.

콘솔도 비슷했습니다. 색 검증 도구의 소스를 페이지에 바로 넣었더니 그 머리 주석에 든 </script> 에서 스크립트가 끊겨 문법 오류가 두 줄 났습니다. 그 뒤 같은 탭에서 다음 페이지로 옮겼는데, 콘솔에 그 두 줄이 그대로 남아 있었습니다. 내장 브라우저의 콘솔 기록은 주소를 옮겨도 지워지지 않았고, 하마터면 새 페이지의 오류로 볼 뻔했습니다. 그 뒤로 콘솔은 새 탭을 열어 읽습니다. 검증 기록의 "콘솔 오류 없음" 옆에 "새 탭"이 붙어 있는 것이 그 때문입니다.

두 도구 모두 틀린 것을 보여 주지는 않았습니다. 보여 준 것은 조금 전의 화면이었고, 읽는 쪽이 그것을 지금으로 읽었습니다.

새벽 3시에 아침의 기록을 찾았다

사이트의 빌딩 숫자는 매일 6시 30분에 자동 작업이 올립니다. 10월 21일 새벽, 사이트 세션이 다른 일을 시작하기 전에 그 작업의 기록부터 읽었습니다. 마지막 줄은 전날 아침 7시 31분의 시험 실행이었습니다. Claude 는 "오늘 아침 6시 30분 자동 갱신 기록이 없다"고 적고, 맡은 일보다 이것부터 보겠다고 했습니다.

바로 다음 명령의 첫 줄이 현재 시각이었고, 03:06 이었습니다. 그날의 6시 30분은 아직 오지 않았습니다. 작업은 6시 30분 일정으로 등록돼 있었고 마지막 종료 코드는 0이었으며, 세 시간 반 뒤 6시 30분 11초에 첫 자동 올림이 기록됐습니다. 주장을 적은 바로 다음에 시각을 쟀기에 한 단계 만에 바로잡혔습니다. 순서가 반대였다면 주장 자체가 나오지 않았을 것입니다.

Navigator 의 시각 함정도 같은 줄기입니다. 세션 기록의 시각과 예약 작업의 마지막 실행 시각은 끝에 Z 가 붙은 UTC 인데, 앞 16자만 잘라 쓰면 날짜와 시·분이 그럴듯하게 나오면서 9시간이 어긋납니다. 틀린 값이 틀려 보이지 않는다는 점이 문제였습니다. 지금은 먼저 시간대를 읽어 이 맥의 시각으로 바꾼 뒤에 자릅니다.

그 밖에 짧게

맥의 파일과 db 에서 다시 읽은 문서가 같은지 볼 때, 정렬한 JSON 문자열끼리 비교하면 -0.0 과 0.0 때문에 "다름"이 나왔습니다. 수로는 같은 값입니다. 비교를 값끼리 하도록 바꿨고, 검증 기록에는 db 문서 8개가 맥의 파일과 값이 모두 같다고 남아 있습니다. "다름"이라는 답을 잘못 읽었던 다른 날의 이야기도 있습니다.

서버는 파일의 수정 시각으로 판과 나이를 봅니다. 시험하려고 뇌 지도 파일을 손으로 복사해 되돌렸더니 내용은 12시 25분 것인데 시각만 새것이 됐고, 바로 뒤에 누른 새로고침 버튼이 10분 기준에 걸려 전체 빌드를 건너뛰었습니다. 손으로 바꾼 파일에 서버의 자가 속은 셈입니다.

오래된 앱 세션에는 대화 횟수 칸이 없었습니다. 없는 칸이 0으로 읽혀 "저장소 없이 한 대화"가 첫 빌드에서 1개만 잡혔고, 기록에서 센 질문 수로 채우자 3개가 됐습니다. 원격이 켜져 있는지를 알려 줄 것 같던 칸은 대부분 세션에 없었고, 앱이 원격 켜짐으로 보고한 세션에도 없었습니다. 이 칸으로는 판단할 수 없어서 원격 표시를 뺐습니다.

진짜 고장도 있었습니다. 서버가 페이지 뼈대를 % 서식으로 채우다가 뼈대 CSS 의 100% 에 걸려 모든 요청이 500 을 냈습니다. 문자열 치환으로 바꿔 고쳤습니다. 이 고장은 모든 요청을 막아서 놓칠 수가 없었고, 앞의 일들은 그럴듯해 보여서 놓칠 뻔했습니다.

정리하면

화면이 비면 대상보다 창부터 봅니다. 가려진 창은 그리기를 멈추고, 페이지는 그래도 보이는 중이라고 답할 수 있습니다. 스크린샷 한 장이 그리기를 다시 깨웠습니다.

움직이는 화면은 멈춘 뒤에 찍습니다. 사진과 코드가 엇갈리면 1초 기다렸다 다시 찍습니다.

콘솔은 새 탭에서 읽습니다. 같은 탭의 기록에는 앞 페이지가 남아 있습니다.

"없다"고 말하기 전에 지금이 몇 시인지부터 잽니다. UTC 시각은 문자를 자르지 않고 시간대를 읽어 바꿉니다.

같은지 볼 때는 겉모양이 아닌 값을 비교합니다. 손으로 되돌린 파일은 서버 눈에 방금 만든 파일입니다.

재는 자가 틀렸던 다른 날의 기록은 계측기를 놓은 날에 따로 모았습니다.

On October 21 I built Claude Navigator. For each of the 49 repositories under ~/claude, it gathers what the repository does, what was done there lately and which Claude session handled it, so it can say where to ask about a piece of work. The same single page runs in two places, a private artifact and a local server on the Mac, and Claude checked the screen with the desktop app's built-in browser.

The pitfall list in this repository's document is sixteen lines long. Several of them were not mistakes in the code. They were moments when what the checking tools showed (screenshots, the console, the clock) was almost read as a fact about the present, and the same thing happened twice that week in a session working on this site. Here are a few of them.

In a covered window, not one staff member showed up

Early on October 20, before putting the Claude building demo on this site, I ran it in a copy with the site's security policy (CSP) attached. The building is a 3D office that shows sessions as staff. The original demo showed 6 staff, but the copy drew only the building: 0 staff, and 0 lines of activity log. The console showed no errors.

The staff vanished the moment the policy went on, so suspecting the policy was natural. I searched for eval-style code the policy might block and found none, and all 11 loaded files returned 200. Forcing the page's hidden state to "visible" and waiting 4 seconds still gave 0. When I reopened the original demo, it dropped to 0 as well. The page itself answered that it was visible, but reading the browser's tab information showed that the built-in browser window itself was covered. A covered window does not receive the frames that redraw the screen (requestAnimationFrame). Taking one screenshot made the screen draw, and 3 seconds later the copy showed 7 staff and 30 lines of activity log. The security policy had nothing to do with it from the start.

The next day I stepped on the same thing in Navigator. When the brain map switches between context regions and repository regions, its dots move to their new places over 750 milliseconds, and with the preview tab in the background this animation stalled, leaving an in-between state with no labels. This time I fixed the page. If the screen is hidden, it draws the final state at once without motion, and even if it slips past the hidden check, it finishes after 1 second whether frames arrive or not. If the page answers that it is visible, as it did with the building, the hidden check cannot filter that case out and only the 1-second deadline remains, and I have not yet measured whether that deadline actually fires in a covered window. The building story, where what I measured in the preview was measured again on the live server, is written up separately in Measuring the Fixed Screen Again Showed What Came Next.

Screenshots and the console showed what was there a moment ago

When Navigator's detail window opens, it smoothly scrolls the page so the window does not cover the spot you pressed. A screenshot taken mid-scroll had no window in it. When I asked through code, the window was open. When a picture and the code disagree, it is easy to trust the picture. Waiting 1 second and taking it again showed the window in place, and the earlier picture had been the screen before the scroll finished.

The console was similar. When I pasted a color-checking tool's source straight into the page, the </script> in its header comment cut the script short and produced two lines of syntax errors. After that I moved to the next page in the same tab, and those two lines were still in the console. The built-in browser's console log did not clear when the address changed, and I very nearly read them as errors from the new page. Since then I read the console in a freshly opened tab. That is why "no console errors" in the verification log has "new tab" next to it.

Neither tool showed anything wrong. What they showed was the screen of a moment ago, and the reader took it as now.

At 3 a.m., Claude looked for the morning's log

The building numbers on this site are pushed by a scheduled job at 6:30 every day. Early on October 21, before starting other work, the site session first read that job's log. The last line was a test run at 7:31 the previous morning. Claude wrote that there was "no record of this morning's 6:30 automatic update" and said it would look at that before the task it had been given.

The first line of the very next command was the current time, and it was 03:06. That day's 6:30 had not come yet. The job was registered on a 6:30 schedule, its last exit code was 0, and three and a half hours later, at 6:30:11, the first automatic push was logged. Because the time was measured right after the claim was written, it was corrected within one step. Had the order been reversed, the claim would never have been made.

Navigator's timestamp pitfall comes from the same root. Timestamps in session logs and the last-run time of scheduled jobs are UTC with a trailing Z, and keeping only the first 16 characters gives a plausible date, hour and minute that are 9 hours off. The problem was that the wrong value did not look wrong. Now the time zone is read first and converted to this Mac's local time before trimming.

A few more, briefly

When checking whether the files on the Mac matched the documents read back from the db, comparing sorted JSON strings came out "different" because of -0.0 and 0.0. As numbers they are the same value. I changed the comparison to compare values, and the verification log records that 8 db documents match the Mac's files in every value. There is also a story from another day about misreading the answer "different".

The server judges a file's version and age by its modification time. When I restored the brain map file by copying it by hand for a test, its content was from 12:25 but its timestamp became new, and the refresh button pressed right afterward hit the 10-minute threshold and skipped the full build. The server's ruler was fooled by a file changed by hand.

Older app sessions had no field for the number of turns. The missing field was read as 0, so the first build counted only 1 "conversation without a repository", and filling it with the question count taken from the logs made it 3. A field that seemed to say whether remote control was on was missing from most sessions, including sessions the app reported as having remote control on. That field could not support a judgment, so I removed the remote indicator.

There was a real breakage too. The server filled in the page skeleton with % formatting, tripped on the 100% in the skeleton's CSS, and every request returned 500. I fixed it by switching to string replacement. This breakage blocked every request, so it could not be missed; the earlier ones looked plausible, so they nearly were.

In short

When the screen is empty, look at the window before the target. A covered window stops drawing, and the page can still answer that it is visible. One screenshot woke the drawing back up.

Take pictures of a moving screen after it stops. When a picture and the code disagree, wait 1 second and take it again.

Read the console in a new tab. The log in the same tab still holds the previous page.

Before saying something "is not there", measure what time it is now. Convert UTC timestamps by reading the time zone, not by cutting characters.

When checking whether things are the same, compare values, not their surface form. To the server, a file restored by hand is a file just made.

Records from other days when the ruler was wrong are collected separately in The Day the Gauges Went In.