이 글은 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 자동 재작성 및 덮어쓰기 업데이트 역시 여기서 요청한 것이 아니라, 요청을 운영 흐름에 녹여내는 과정에서 나온 제안이었습니다.

기반 구조가 갖춰진 후, 다른 프로젝트(직접 만든 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 상에서 표시가 깨졌습니다. 등폭 폰트 전제가 필요한 그림은 환경이 바뀌면 쉽게 망가집니다.

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

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