이 글은 Claude (Sonnet 5)와 함께 작성했습니다.

Claude Desktop의 Code 탭에서 처음에 요청한 것은 이 전부였습니다.

Qiita에 글을 쓰는 프로젝트를 새로 만들고 싶어. 초안을 같이 만들어서 API로 전송하고 싶어.

완성된 것은 qiita-writer라는 작은 프로젝트입니다.

drafts/*.md:
frontmatter(title/tags/private/id)가 포함된 초안 Markdown -

scripts/post.js:
초안을 Qiita API v2에 게시 및 업데이트하는 CLI. 첫 실행 시에는 POST하고, 반환된 기사 ID를 frontmatter에 자동으로 다시 기록합니다. 다음부터는 PATCH로 덮어쓰기 업데이트가 됩니다. -

scripts/list.js:
자신이 게시한 기사 목록을 확인하는 CLI -

scripts/frontmatter.js:
의존 라이브러리 없는 간편 frontmatter 파서

'초안을 만들고 API로 전송하고 싶다'는 한 문장이 단순히 '게시하고 끝'이 아니라, '게시 후에도 수정하며 발전시킨다'는 전제에 맞춰 설계가 번역되었습니다.

기사 ID의 자동 기록 및 덮어쓰기 업데이트 역시 여기서 요청한 것이 아니라, 요청을 운영 흐름(workflow)에 녹여내는 과정에서 나온 제안이었습니다.

뼈대가 갖춰진 후, 다른 프로젝트(직접 만든 Android 앱의 한정 배포 포털)의 README를 전달하며 '이 내용으로 기사를 써달라'고 요청했습니다. README는 개발자용 설명서이기 때문에 그대로 붙여도 기사가 되지는 않습니다. 독자를 예상한 제목 구성으로 재배치하고, 코드는 기사로 읽을 분량에 한정하는 변환 과정을 거쳐 Qiita 형식의 기사로 작성되었습니다.

도중에 '게시 전에 초안 상태로 할 수 없나요?'라고 물어봤더니, Qiita API v2에는 진정한 의미의 '미공개 초안' 상태가 없다고 알려주었습니다(전혀 찾아보지 않았기 때문에).

선택할 수 있는 것은 다음 두 가지뿐입니다.

• private: false → 공개 -
• private: true → 한정 공유 (URL을 아는 사람만 볼 수 있음)

그래서 'private: true로 게시하고, 수정 후 private: false로 전환하여 공개한다'는 운영 방식에 결정되었습니다.

• 기사 시작 부분에 Claude와 함께 작성했음을 명시하는 한 줄을 반드시 넣기
• 초안은 반드시 private: true로 만들고, 명시적인 공개 지시가 있을 때까지 private: false로 변경하지 않기

이것들은 대화 중에 그때그때 전달하는 것이 아니라, AGENTS.md에 '무너뜨려서는 안 되는 불변 조건'으로 작성했습니다.

대화 속의 약속은 세션이 끝나면 사라지지만, 파일에 적힌 규칙은 다음 세션에서도 아무 말 없이 지켜집니다.

첫 번째 기사에서는 ASCII 아트를 사용해 그림을 그렸는데, Qiita 상에서 표시가 깨졌습니다. 고정폭 글꼴(monospace font) 전제가 필요한 그림은 환경이 바뀌면 쉽게 망가집니다.

Qiita는 mermaid 코드 블록에 네이티브 대응하고 있으므로, 이후로는 모든 그림을 mermaid로 그리기로 하고, 이것도 AGENTS.md에 명시했습니다.

mermaid로 전환한 후에도 한 가지 함정이 있었습니다. 노드 레이블 안에서 줄 바꿈을 하고 싶어서 `