Claude CodeでCITATION.cffを作り、論文でソフトウェアを引用可能にする

CITATION.cffは、ソフトウェアの引用情報を機械可読にしたファイル

CITATION.cffは、ソフトウェアやデータセットの引用情報を書くプレーンテキストのファイルです。形式はCitation File Format(CFF)で、リポジトリのルートに置きます。人が読めて、ツールも読めます。

論文なら、タイトルや著者は表紙に書いてあります。ソフトウェアには表紙がありません。引用したい人は「名前はanalysis.pyでいいのか」「どの版を使ったと書くのか」「著者は誰なのか」を自分で決めることになります。CFFのサイトは、この3つの疑問に作者が先に答えておくためのファイルだと説明しています。

Claude Codeに任せて速くなるのは、pyproject.tomlやLICENSEに散らばった情報を集めて下書きにする作業と、検証を回す作業です。逆に、著者の並びとORCIDは人が決めます。この記事では、下書きの作成、検証、GitHubの引用表示、Zenodoとの連携までを順に組みます。

最小のCITATION.cffは4キーで足りる

必須のキーは、cff-version、message、authors、titleの4つです。スキーマのガイドに、この4つだけの最小例が載っています。

authors:
  - family-names: Druskat
    given-names: Stephan
cff-version: 1.2.0
message: "If you use this software, please cite it using these metadata."
title: "My Research Software"

実際に引用される文書にしたいなら、次のキーも足します。

文字列が思いどおりに読まれないときは、引用符で囲むのがガイドの助言です。手元のcffconvert 2.0.0でversion: 1.20と引用符なしで書くと、変換結果の版は1.2になりました。数値として読まれて末尾の0が落ちるため、版は引用符付きで書きます。

Claudeが拾える項目と、拾わせない項目

下書きづくりで先に決めるのは、Claudeに何を読ませ、何を書かせないかです。リポジトリに根拠があるものは拾えます。根拠がないものは、推測で埋めさせません。

著者をgit shortlogだけで決めてはいけません。コミット数の多い順は、貢献の大きさも、論文での著者順も表していません。ORCIDは本人しか知らない情報です。ここを埋めさせると、実在しないIDや別人のIDが入ります。CLAUDE.mdに規則として書いておきます。

## CITATION.cff の規則
 
- authors と orcid は、リポジトリ内に根拠がある値だけ書く。無ければ書かずに質問する
- version は pyproject.toml と最新のgitタグを突き合わせ、食い違えば報告する
- license は SPDX 識別子で書く(MIT, Apache-2.0 など)。判別できなければ空にする
- 編集後は必ず `cffconvert --validate` を実行し、結果を報告する

pyproject.tomlから下書きを作らせる

具体例で考えます。次のようなpyproject.tomlがあるとします。

[project]
name = "sample-tool"
version = "0.3.1"
license = { text = "MIT" }
authors = [{ name = "Taro Yamada", email = "taro@example.com" }]

依頼は次のように短く、根拠の範囲を添えて出します。

pyproject.toml、LICENSE、git の情報から CITATION.cff を作って。
authors と orcid はリポジトリに根拠がある分だけ。
最後に cffconvert --validate の結果を見せて。

例えば次のような形になります。値はこのpyproject.tomlに対応させた例示で、ORCIDは本人に確認してから入れます。

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "sample-tool"
version: "0.3.1"
date-released: "2026-10-01"
license: MIT
repository-code: "https://github.com/example/sample-tool"
authors:
  - family-names: Yamada
    given-names: Taro

pyproject.tomlのauthorsはnameが「Taro Yamada」と一続きです。CFFはfamily-namesとgiven-namesに分けて書くので、姓名の分割は誤りやすい箇所です。日本語の氏名を扱う場合は、ローマ字表記を論文の著者欄と揃えるよう、人が確認します。

cffconvertで検証する

CFFの検証には、公式が案内するコマンドラインツールのcffconvertを使います。READMEによると、検証と変換の両方ができ、出力形式はAPA風テキスト、BibTeX、CodeMeta、EndNote、RIS、schema.org JSON、Zenodo JSONです。

手元の空の仮想環境に入れ、上の例に近いファイルで試しました。cffconvertのバージョンは2.0.0です。

python3 -m venv .venv && .venv/bin/pip install cffconvert
.venv/bin/cffconvert --validate

正しいファイルなら、次の1行が返り、終了コードは0です。

Citation metadata are valid according to schema version 1.2.0.

壊してみると、挙動の癖がはっきりします。messageの行を消すと、'message' is a required propertyのValidationErrorになり、終了コードは1でした。license: MITをMITTに変えた場合は、受け付けるSPDX識別子の全一覧が表示されました。

ここで気をつけたいのは出力量です。エラー時はスキーマ全体が流れ、手元では1回で約1000行になりました。Claudeに丸ごと読ませるとコンテキストを無駄に使うため、必要な1行だけに絞ります。

cffconvert --validate 2>&1 | grep -E "valid|ValidationError" | cut -c1-200

変換も同じツールで行えます。

cffconvert -f bibtex
cffconvert -f apalike

上のファイルでは、APA風がYamada T. (2026). Sample Tool (version 0.3.1). URL: https://github.com/example/sample-toolになりました。BibTeXは@misc型で、引用キーがYourReferenceHereという仮の名前でした。論文に貼る前に、キーとエントリ型を自分で直す前提で使います。

READMEには、referencesとpreferred-citationの変換には対応していないとも書かれています。論文向けのpreferred-citationを書いた場合、cffconvertの変換結果は検証の補助と考え、表示の確認はGitHub側で行います。

保存のたびに検証するフックを置く

検証を依頼文に書くだけでは、Claudeが忘れる日があります。Claude Codeのフックなら、編集のたびに必ず走ります。PostToolUseは、ツール呼び出しが成功した直後に動くイベントです。終了コード2で返すと、標準エラー出力がClaudeに見えます。

設定は.claude/settings.jsonに書きます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-cff.sh"
          }
        ]
      }
    ]
  }
}

スクリプトは、標準入力のJSONから編集したファイルのパスを取り、CITATION.cff以外なら何もせず終わります。

#!/bin/bash
f=$(jq -r '.tool_input.file_path // empty')
[[ "$f" == */CITATION.cff ]] || exit 0
if ! out=$(cffconvert --validate -i "$f" 2>&1); then
  echo "$out" | grep ValidationError | cut -c1-200 >&2
  exit 2
fi

chmod +xを忘れずに。これで、messageを消した編集や、存在しないライセンス識別子を書いた編集は、その場でClaudeに差し戻されます。

人間がコミットするときの検証には、cffconvertが提供するpre-commitフックが使えます。.pre-commit-config.yamlにvalidate-cffのフックを足す形です。READMEのリビジョンはコミットのハッシュで固定されているので、書き写すときは最新のREADMEで確認します。

GitHubの「Cite this repository」に何が出るか

CITATION.cffを既定ブランチに置くと、リポジトリのトップの右サイドバーに「Cite this repository」のリンクが出ます。クリックすると、APAとBibTeXの引用が表示され、コピーできます。GitHubの説明では、通常のCITATION.cffからは@software型のBibTeXになります。先ほどのcffconvertが@miscを返したのとは異なるため、表示の確認はGitHubの画面で行います。

論文を引用してほしいときは、preferred-citationを使います。GitHubの引用表示が、ソフトウェアそのものではなく指定した論文に向きます。

preferred-citation:
  type: article
  authors:
    - family-names: Yamada
      given-names: Taro
  title: "A tool for sample analysis"
  journal: "Journal Title"
  year: 2026
  doi: "10.0000/00000"

ただし、CFFのスキーマガイドは、別の文献を優先引用にすると、ソフトウェアも他の研究成果と同じ基準で引用すべきだという原則(Importance)に反する恐れがあると注記しています。論文が成果の中心ならこの形が自然ですが、ソフトウェア自体を引用してほしい場面では、使わないほうが筋に合います。

データセットを含むリポジトリでは、トップレベルにtype: datasetを書くと、データ引用の形式で出力されます。

Zenodo連携でDOIをつなぐ

DOIが欲しい場合は、GitHubのリリースをZenodoに自動保存します。連携を有効にするには、ZenodoにGitHubアカウントをつなぎ、プロフィールのメニューからGitHubを開いて「Sync now」を押し、対象リポジトリのスイッチをオンにします。以降、新しいリリースが自動で取り込まれます。

CITATION.cffとの関係で、押さえる点は3つです。

1. ZenodoはCFFのスキーマの一部だけを実装しています。サポートされるフィールドの例として、title、version、license、type、abstract、authors(affiliationとorcid付き)、keywordsがドキュメントに載っています
2. リポジトリに.zenodo.jsonもあると、Zenodoはそちらだけを使い、CITATION.cffを無視します。それでも、GitHubの引用表示に使われるため、CITATION.cffは置いておくことが推奨されています
3. DOIはZenodoでの最初の保存後に決まるので、最初のリリースのCITATION.cffには書けません

三つ目は、手順の順序に効きます。最初のリリースは、DOIなしのCITATION.cffで作ります。保存後に発行されたDOIをidentifiersに足し、次のリリースに含めます。CFFのガイドは、identifiersに二種類のDOIを並べる例を示しています。全バージョンを束ねるDOIと、特定の版のスナップショットを指すDOIです。引用してほしいのが「その版」なのか「ソフトウェア全体」なのかを、descriptionで書き分けます。

identifiers:
  - description: "All versions of sample-tool"
    type: doi
    value: 10.5281/zenodo.123456
  - description: "Version 0.3.1 of sample-tool"
    type: doi
    value: 10.5281/zenodo.123457

DOI値は仕様書の例に沿った仮のものです。アーカイブ前に研究データの側で何を確かめるかは、Zenodoに研究データを公開する前の点検で扱っています。

リリースごとの更新をスキルにする

CITATION.cffで最も古びやすいのは、versionとdate-releasedです。リリースのたびに手で直す運用は、忘れた時点で破綻します。リリース前の更新手順を、Claude Codeのスキルにしておきます。

.claude/skills/update-cff/SKILL.mdに、次のように書きます。

---
name: update-cff
description: リリース前に CITATION.cff の version と date-released を更新して検証する
disable-model-invocation: true
allowed-tools: Read Edit Bash(cffconvert *) Bash(git describe *)
---
 
## 最新のタグ
 
!`git describe --tags --abbrev=0`
 
## 手順
 
1. 上のタグと pyproject.toml の version が一致するか確認する。食い違えば報告して止まる
2. CITATION.cff の version と date-released を更新する(date-released は引用符付き)
3. `cffconvert --validate` を実行し、結果を報告する

disable-model-invocation: trueにすると、Claudeが勝手に読み込まず、/update-cffと入力したときだけ動きます。リリース作業は意図したタイミングでだけ走らせたいので、この設定が合います。allowed-toolsは、そのターンの間だけ承認なしで使えるツールを指定します。コマンドはcffconvertとgit describeに絞りました。

この仕組みは、論文の手法を再実装する作業や、OpenAlex APIで引用関係を調べる作業のように、研究ソフトウェアを軸にした工程の最後にも置けます。

つまずきやすい箇所

ほかにも、次の点でつまずきます。

• ORCIDはURL形式で書く。ガイドの例は"https://orcid.org/0000-0002-1825-0097"の形です。番号だけ(0000-0002-1825-0097)で書くと、cffconvert 2.0.0の検証はhttps://orcid.org/で始まる形式に一致しないとして弾きます
• date-releasedは引用符で囲む。ガイドの例は引用符付きです。引用符なしでもcffconvert 2.0.0の検証は通ったため、検証だけでは書き方の揺れに気づけません
• .zenodo.jsonの置き忘れに注意する。古い手順で作った.zenodo.jsonが残っていると、CITATION.cffを直してもZenodoの記録に反映されません
• messageの文言を変えるときは、データセット向けとソフトウェア向けを取り違えない。ガイドは両方の例文を載せています
• ツールの出力をそのまま信じない。cffconvertのBibTeXと、GitHubの表示は別物です。論文に貼る前に、引用キーとエントリ型を自分で確認します

まとめ

CITATION.cffは、作者が引用の答えを先に書いておくためのファイルです。Claude Codeに向く作業は、pyproject.tomlやgitから事実を集める下書きと、検証の反復です。著者の並び、ORCID、論文を優先引用にするかどうかは、人が決めます。

運用は、CLAUDE.mdで「根拠のない値は書かない」を固定し、PostToolUseフックで編集のたびに検証し、リリース前のスキルでversionを揃える形にすると回ります。DOIはZenodoでの初回保存の後に決まるため、1回目のリリースでは空のまま出し、2回目以降にidentifiersへ足す順序になります。