API 명세 68페이지에서 팀 수정 148곳 지키기

팀의 Notion API 명세 68페이지를 코드와 대조했습니다. 요청과 응답의 필드, 오류가 나는 조건, 예제의 타입이 구현과 맞는지 확인해 교정안을 만들었습니다. 하루 뒤 적용하려고 문서를 다시 읽으니 교정 후보 1,033곳 중 148곳은 팀원이 이미 다른 문구로 바꾼 상태였습니다. 81곳은 페이지가 개편되거나 작업이 취소되면서 대상 행이나 표를 찾을 수 없었습니다. 검토가 끝난 교정안이라도 그대로 덮어쓰면 그사이 팀이 고친 내용을 되돌릴 수 있었습니다.

기존 문구가 일치할 때만 수정

교정안에는 페이지와 표에서 바꿀 위치, 검토할 때의 문구, 바꾸려는 문구를 함께 적었습니다. 적용 직전에는 문서를 다시 읽고 세 값을 대조했습니다.

비교할 때는 정리 대상인 공백과 줄바꿈 차이를 걷어 내고 문구 전체를 확인했습니다. 예를 들어 GET /items에 검색 조건을 붙이는 교정안이 있다고 해 보겠습니다. 문서에 이미 GET /items?sort=recent가 들어 있는데 앞부분만 보고 교체하면 검색 조건이 두 번 붙을 수 있습니다. 비슷한 제목의 행이 둘 이상 있을 때도 셀의 전체 문구와 표 안의 위치를 함께 확인해야 같은 이름의 다른 행에 쓰지 않습니다.

이 기준으로 팀원이 고친 148곳은 현재 문구를 살리고 줄바꿈만 정리했습니다. 찾을 수 없었던 81곳은 대상 없음으로 남겼습니다. 쓰기 요청에도 방금 읽은 원문을 교체 조건으로 넣어, 페이지에서 한 곳으로 식별되는 구간을 골라 바꿨습니다.

저장한 문서를 다시 대조

작업자가 표의 긴 셀을 일일이 옮기면 글자 하나가 달라질 수 있습니다. 저는 조회한 텍스트에서 스크립트로 교체 요청을 만들고, 반영 뒤에는 저장된 문서를 다시 읽어 같은 비교를 실행했습니다. 한 차례 원문을 옮겨 적는 과정에서 생긴 오타 때문에 두 건이 저장되지 않았습니다. 저장본으로 후보를 다시 계산하니 그 두 곳이 여전히 수정 대상으로 나와 고칠 수 있었습니다.

같은 문서 도구로 표를 편집할 때는 값이 같아도 서식이 달라지는 경우를 봤습니다. 점이 들어간 파일 이름을 저장하자 링크로 바뀌었습니다. 코드 서식으로 감싸 자동 링크를 막았는데, 처음 쓴 정규식은 파일 이름 바로 뒤의 한글 조사까지 감쌌습니다. 일치 범위를 식별자까지만 좁혀 조사는 바깥에 남겼습니다. 이 사례는 저장 시 생기는 서식 차이를 확인한 기록입니다.

재조회에서는 바꾼 칸이 의도한 값인지, 요청에 담지 않은 칸에도 차이가 생겼는지를 따로 봤습니다. 별도로 테스트 문서 47행에 두 속성을 넣고 다시 읽었을 때는 한 행에서 글자 하나가 다르게 저장된 것을 발견했습니다. 같은 비교에서 네 행의 다른 칸에도 차이가 있었습니다. 그 칸들은 제 요청에 없었으므로, 동시 편집 가능성이 있는 변경으로 구분했습니다.

명세 검토의 초기 작업에서는 7페이지를 수정한 뒤 저장본을 확인했습니다. 이후 수동으로 반영한 문서 전체를 저장본과 다시 대조한 기록까지는 확보하지 못했습니다. 1,033은 비교에 올린 교정 후보의 수입니다. 저장 여부는 다시 읽어 일치가 확인된 범위에서 판단했습니다.