2026년 11월 16일, 저는 AI와 함께 Qiita 기사를 작성하고 내용을 확인한 후, '좋다'고 공개를 승인했습니다.
AI는 공개용 스크립트를 실행했고, Qiita API로부터 다음 결과를 받았습니다.
{
"status": "published",
"http_status": 201,
...
}
기사는 전체적으로 공개되었고, 제목, 태그, 본문 모두 로컬 원고와 일치했습니다.
여기까지만 보면 작업이 완료된 것처럼 보입니다.
하지만 공개 후에 로컬 관리표를 확인했더니, 해당 기사의 상태는 여전히 다음 상태였습니다.
Qiita에서는 이미 공개되었는데, 제가 가진 기록에는 아직 미공개 상태인 것입니다.
이번 글에서는 어제 실제로 발생했던 이 불일치 상황과, AI의 성공 보고만으로 작업을 끝내지 않고 외부 서비스 결과와 수동 기록을 대조한 과정을 소개합니다.
어제 공개된 기사는 다음 기사입니다.
공개 스크립트는 투고 전에 같은 제목의 기사가 없는지 확인하고, 저의 승인 후에 Qiita API로 투고했습니다.
API 응답에서는 다음 항목들을 확인할 수 있었습니다.
| 확인 항목 | 결과 |
|---|
| HTTP 상태 코드 | 201 |
| ... | |
| 즉, 'Qiita에 기사를 공개한다'는 외부 서비스 측의 처리는 성공했습니다. | |
브라우저에서 열 수 있는 공개 URL도 있습니다. 투고가 실패한 것이 아닙니다.
문제는 그 결과가 로컬 관리표에 반영되지 않았다는 것입니다.
이 프로젝트에서는 기사별 상태를 PUBLISH_SCHEDULE.json으로 관리하고 있습니다.
공개 전의 기사는 다음과 같은 정보를 가집니다.
{
"vol": "103",
"planned_date": "2026-11-16",
...
ready는 원고와 이미지 준비가 끝났고, 공개 전 검사도 통과한 상태입니다. 아직 공개된 것은 아닙니다.
공개 후에는 원래 다음과 같은 정보가 필요합니다.
{
"state": "published",
"published_at": "공개 일시",
...
그런데 API가 공개 성공을 반환한 직후 관리표를 다시 읽어보니, state는 여전히 ready 상태였습니다. 기사 ID, URL, 공개 일시도 기록되어 있지 않았습니다.
이대로 두면, 다음번에 관리표만 읽는 AI나 사람이 해당 기사를 '아직 공개하지 않았다'고 판단할 가능성이 있습니다.
게다가 같은 기사를 다시 공개하려는 진입점(entry point)이 될 수도 있습니다. 공개 스크립트에는 제목 중복 확인 기능이 있지만, 관리표와 실제 상태가 불일치한 채로 두어서는 안 됩니다.
불일치를 발견한 후, 저는 공개 스크립트의 처리 과정을 확인했습니다.
실제로 수행된 것은 주로 다음 처리였습니다.
공개 예정일 기사를 관리표에서 선택한다
state가 ready인지 확인한다
같은 제목의 기사가 Qiita에 없는지 확인한다
...
반면, 스크립트 내부에는 관리표를 수정하는 처리가 없었습니다.
공개 결과를 JSON 형태로 화면에 표시할 뿐, 그 결과를 PUBLISH_SCHEDULE.json에 저장하지 않았습니다.
이것은 스크립트가 거짓된 성공 보고를 했다는 의미가 아닙니다.
스크립트가 담당했던 범위는 Qiita로 투고하고, 직후 대조하는 것까지였습니다. 로컬 기록 업데이트는 별도의 작업으로 남아있었던 것입니다.
공개 스크립트의 성공
≠
공개 작업 전체의 기록 완료
저는 이 둘을 같은 것으로 보고 있었습니다.
어제는 공개 성공 결과를 받은 후, 다음 순서로 확인했습니다.
API 응답으로부터 기사 ID, 공개 URL, 공개 일시, 전체 공개 여부, 태그, 본문 일치 여부를 확인했습니다.
여기서는 외부 서비스에서 무슨 일이 일어났는지 확인하는 것입니다.
관리표의 Vol.103을 확인하니, state가 ready인 상태임을 알았습니다.
공개 전에 읽었던 내용을 기억에 의존하지 않고, 공개 후 파일을 다시 읽었습니다.
스크립트를 읽어 Qiita 투고와 대조는 하지만, 관리표를 업데이트하는 처리는 없다는 것을 확인했습니다.
'우연히 업데이트에 실패했다'고 단정 짓지 않고, 애초에 업데이트할 설계였는지 여부를 확인했습니다.
Qiita API가 반환한 사실을 사용하여, 관리표에 다음 내용을 추가했습니다.
state: published
published_at: 2026-11-16T08:46:31+09:00
item_id: 9f8e4b66823c655d55e9
...
업데이트 후, 관리표를 JSON으로 읽을 수 있는지 검사하고 Vol.103의 상태, 기사 ID, URL, 공개 일시를 재표시했습니다.
최종 결과는 다음과 같습니다.
state: published
item_id: 기록됨
url: 기록됨
...
이로써, Qiita 측과 수동 관리표가 동일한 상태가 되었습니다.
이번 작업에는 최소한 3가지의 성공이 있었습니다.
| 단계 | 성공의 의미 |
|---|
| 게시 성공 | Qiita API가 기사를 생성함 |
| ... | |
| 첫 번째 것만으로 작업을 마치면, 공개가 되었더라도 기록이 남지 않습니다. | |
반대로, 관리표만 published로 변경하더라도, Qiita에 기사가 존재하지 않으면 공개 성공이라고 할 수 없습니다.
외부 서비스의 실체
로컬 원고
로컬 관리 기록
이 3가지가 일치해야 이번 작업이 완료됩니다.
복잡한 모니터링 시스템을 만든 것이 아닙니다. 공개 후에 외부와 수동으로 한 번씩 다시 읽어본 것뿐입니다.
'AI의 성공 보고를 믿지 않는다'고 하면, AI가 잘못된 보고를 한 것처럼 들릴 수 있습니다. 이번은 그렇지 않습니다.
AI가 실행한 스크립트는 Qiita API 결과를 올바르게 반환했습니다. 공개 기사도 원고와 일치했습니다.
부족했던 것은 '공개가 성공하면, 관리표도 자동으로 업데이트될 것이다'라는 저의 착각이었습니다.
AI에게 작업을 맡길 때는 다음 두 가지를 분리해야 합니다.
도구가 실행한 범위
제가 완료로 간주하고 싶은 범위
도구의 범위가 게시까지라면, 기록 업데이트는 별도로 필요합니다.
AI에게 '공개해 달라'고 요청하는 경우에도, 완료 조건을 다음과 같이 구체화할 수 있습니다.
기사를 전체 공개해주세요.
공개 후에, 기사 ID, URL, 공개 일시, 본문 일치를 확인해주세요.
로컬 관리표가 published 상태인지도 확인해주세요.
...
이번에는 공개 스크립트에 관리표 자동 업데이트 기능을 추가하지 않았습니다.
실제로 수행한 것은 공개 결과 확인과 관리표 수동 업데이트입니다. 따라서 이 글에서는 '앞으로는 반드시 자동 동기화될 것이다'라고 쓸 수 없습니다.
다음에도 같은 스크립트를 사용할 것이라면, 공개 후에 관리표를 확인할 작업이 필요합니다.
미래에 스크립트에 자동 업데이트를 추가하더라도, 다음과 같은 실패 사례를 고려해야 합니다.
Qiita로의 공개는 성공했으나, 관리표 저장에 실패하는 경우
관리표는 업데이트되었으나, Qiita로의 공개에 실패하는 경우
공개 후 본문 확인에 실패하는 경우
다만, 이것은 아직 구현하지 않은 개선안입니다. 현재 운영 방식은 API 결과를 확인하고, 사람이 관리표의 업데이트 결과까지 확인하는 수준입니다.
이번 실무 작업에서 다음에도 사용할 수 있는 최소 체크리스트를 정리했습니다.
[ ] 공개 URL을 열어볼 수 있다
[ ] 전체 공개 상태이다
[ ] 제목과 태그가 일치한다
...
처음부터 자동화를 다시 만들지 않아도, 이 6가지 항목을 공개 후에 한 번 확인하면 이번과 같은 불일치에 알아챌 수 있습니다.
어제, Qiita 게시물은 성공했습니다. 하지만 로컬 관리표는 ready 상태 그대로였습니다.
실제로 수행한 대응은 다음과 같습니다:
- Qiita API의 공개 성공을 확인했다
- 전체 공개, 제목, 태그, 본문 일치를 확인했다
- 로컬 관리표를 다시 읽어보았다
state가 ready 상태로 남아있는 것을 발견 — 공개 스크립트에 관리표 업데이트 처리가 없다는 것을 확인했다
- API 결과를 관리표에 수동으로 기록했다
- JSON을 재검사하여 외부와 수동의 상태를 일치시켰습니다.
AI가 '성공했습니다'라고 보고했을 때, 즉시 의심할 필요는 없습니다. 그 성공이 어디까지를 의미하는지 확인합니다.
이번 첫걸음은, 공개나 전송 등 외부 서비스를 변경하는 작업 후에 다음 문장을 AI에게 요청하는 것입니다.
외부 결과뿐만 아니라, 수동 관리 기록도 같은 상태가 되었는지 확인해주세요.
성공 표시는 작업의 종점이 아니라, 기록과의 대조를 시작하는 신호였습니다.