はじめに
こんにちは。トライベック株式会社の高橋です。
業務でBacklogを使ってタスク管理を行っているのですが、最近Claude CodeのBacklog MCPを使って起票を任せたところ、本文にマークダウン記法（# 見出しや 強調、``` コードフェンスなど）が混入してしまい、Backlog上でフォーマットが崩れる問題に悩まされました。
「Backlog記法で書いて」と指示してもいい感じのフォーマットにならず、毎回手直しが発生する懸念がありました。
なお、Backlogはプロジェクト単位でMarkdown記法も選べるので、新規プロジェクトや途中で変更が可能ならそちらにする方が早いです。今回は 私が参加している既存プロジェクトが全てBacklog記法で運用されており、AI起票のためだけに全プロジェクトの運用を変えるのは現実的でない という前提で、Claude Code側を合わせさせる方向で設計しました。
実際にどう崩れていたか
まず、どんな状態だったかを見ていただくのが早いと思います。
Before: マークダウン記法が混入してフォーマットが崩れている状態
# 見出しや **強調** がそのまま表示されてしまっています。
After: 今回の構成を入れてBacklog記法で整形された状態
見出し、強調、リスト、コードブロックが全てBacklogのフォーマットで正しく表示されています。
この差を作ったのが、これから紹介する CLAUDE.md + ~/.claude/docs/ を組み合わせた設計です。
検討した案
最初に思いついたのは ~/.claude/rules/ フォルダにルールファイルを置く方法でした。
~/.claude/rules/ 内のマークダウンファイルはClaude Code起動時に自動的に読み込まれるため、Backlog書き込み時にも自動でルールが適用されるはず、と考えました。
しかし、よく考えると ~/.claude/rules/ は「起動時に必ず全部読まれる」仕様 です（厳密には paths: フロントマターで条件付きロードもできますが、これはファイルパスベースの判定のため、今回のような会話文脈で発火させたいケースには使えません）。つまり今回のように「Backlogに書き込む時だけ意識してほしいルール」を置いてしまうと、 Backlogと無関係なタスク(コーディング、調査、雑談、別ツールの操作など)でも毎回ルールがコンテキストに乗ってしまう ことになります。
新しいルールが増えていったら、 無関係なタスクでもコンテキストをどんどん圧迫する ことになる。これは避けたい。
そこで、 「該当タスクが来た時だけ必要なルールが読まれる」=オンデマンドで適用される仕組み を作る方向で設計を詰めることにしました。
正解の構成: .claude/docs/ を使う
公式ドキュメントおよび Claude Code コミュニティの記事を漁った結果、 オンデマンドで参照させたいドキュメントは .claude/docs/ に置く というやり方があると知りました。
The
.claude/docs/directory holds reference documents that skills read on demand. ... Rules load automatically. That's the problem. ... Docs stay dormant until a skill explicitly reads them.
（.claude/docs/はスキルがオンデマンドで読む参照ドキュメントを置く場所。rulesは自動ロードされるのが問題。docsは明示的に読まれるまで休眠している）
.claude/docs/ は 公式ドキュメントには記載されていない非公式の慣習 ですが、rules/ の自動ロード問題を回避するパターンとして広く使われています。
ディレクトリ役割の整理
| ディレクトリ | ロードタイミング | 用途 |
|---|---|---|
~/.claude/CLAUDE.md |
起動時に必ず | 全タスクで参照される基本ルール / ディスパッチ |
~/.claude/rules/ |
起動時に必ず（全マークダウン） | 常時意識してほしいルール |
~/.claude/docs/ |
明示的に読まれた時のみ | 特定タスクで参照される詳細ルール |
~/.claude/skills/ |
/skill-name で明示呼び出し、またはdescriptionにマッチした時に自動発火 |
タスクをこなす手順 |
今回欲しかった「Backlog書き込み時だけ詳細ルールを参照」は、 CLAUDE.md(常駐) + docs/ (オンデマンド) の組み合わせで実現できます。
設計の全体像
~/.claude/ ← Claude Codeのユーザーグローバル設定ディレクトリ
│ Windows: C:\Users\<ユーザー名>\.claude\
│ macOS/Linux: /Users/<ユーザー名>/.claude/
│
├── CLAUDE.md ← 短い案内（ディスパッチ）
│ 全セッションで自動ロードされる
│ 既存ファイルがあれば末尾に追記、なければ新規作成
│
└── docs/ ← オンデマンド参照用のフォルダ（自分で新規作成）
└── backlog-syntax.md ← ルール本体（必要な時だけ読まれる）
新規作成
各ファイル・フォルダの状態は以下です:
-
~/.claude/フォルダ: Claude Codeを使い始めていれば既に存在(隠しフォルダ) -
~/.claude/CLAUDE.md: 存在しなければ新規作成、既存なら末尾に追記 -
~/.claude/docs/フォルダ: デフォルトでは存在しないので、自分で作成 -
~/.claude/docs/backlog-syntax.md: 新規作成
CLAUDE.md には 「Backlog書き込み系のリクエストが来たら、このファイルを必ず読め」という案内だけ を書いておく。Claudeは関係ないタスクの時はこの案内を素通りし、Backlog書き込みリクエストを検知した時だけ docs/backlog-syntax.md を読みに行く。
これで:
- 無関係なリクエスト時 → CLAUDE.md の数行だけがコンテキストに乗る（軽量）
- Backlog書き込み時 → 詳細ルールがオンデマンドで読まれる（フォーマット崩れ防止）
作成したファイル
1. ~/.claude/CLAUDE.md に追記する内容
将来別のルールも追加しやすいよう、番号付きセクションで拡張可能な構造 にしました。
# カスタムルール
このセクションには、特定のタスクに対して適用すべきルールを記載する。
該当するリクエストを受けたら、指定された参照ファイルを **必ず先に読んでから** タスクを開始すること。
ルールを読まずに本文・コメント・コードを生成した場合は、出力を破棄してやり直すこと。
---
## 1. Backlog書き込み時のルール
**該当リクエスト例:**
- 新規起票: 「Backlogに起票」「チケット切って」「issue作って」「課題立てて」「タスク登録」
- 本文更新: 「Backlogの○○を更新」「課題の本文を直して」
- コメント: 「Backlogにコメント」「○○にコメント追加」「コメント編集」
**参照ファイル:** `~/.claude/docs/backlog-syntax.md`
---
## 2. (ここに次のルールを追加)
ポイント:
- 共通の強制力（「読まずに生成したら破棄」）は冒頭にまとめて、各ルールごとに毎回書かなくていい構造
- 「該当リクエスト例」「参照ファイル」 の固定フォーマットで、新ルール追加時に何を埋めればいいか迷わない
- 番号付きセクション で並び替え・追加・削除しやすい
2. ~/.claude/docs/backlog-syntax.md（ルール本体）
Backlog記法の主要要素を網羅し、各項目で マークダウンとの対比 を明示して「これは使うな」を強調しました。さらに本文生成後の セルフチェックリスト も入れています。
# Backlog記法ルール
Backlogへの **起票本文・課題本文更新・コメント投稿/編集** を行う際は、
このファイルのルールに従って本文を整形すること。マークダウン記法は **絶対に使わない**。
---
## 1. 見出し
```
* 見出し1
** 見出し2
*** 見出し3
```
❌ マークダウンの `#` `##` `###` は使わない
## 2. 強調
```
''斜体''
'''太字'''
'''''太字斜体'''''
%%%取り消し線%%%
```
❌ マークダウンの `*斜体*` `**太字*` は使わない
## 3. リスト
```
- 項目1
- 項目2
-- ネスト項目
--- さらにネスト
+ 番号付き項目1
+ 番号付き項目2
++ ネスト項目
```
注意: Backlogのリストは `-` の直後にスペース不要。マークダウンと混同しやすい。
## 4. コードブロック
```
{code}
コード本文
{/code}
{code:python}
print("言語指定もできる")
{/code}
```
❌ マークダウンの ` ``` ` フェンスは使わない
✅ コードブロック内のテキストはそのまま保持(中のマークダウン風記述を変換しない)
## 5. インラインコード
```
{{インラインコード}}
```
❌ マークダウンの `` `code` `` (バッククォート) は使わない
## 6. 引用
```
> 引用文
> 複数行も可
```
## 7. リンク
```
[[表示テキスト>https://example.com]]
[[https://example.com]]
```
❌ マークダウンの `[text](url)` は使わない
## 8. 表
```
| ヘッダ1 | ヘッダ2 | ヘッダ3 |h
| セル1 | セル2 | セル3 |
| セル4 | セル5 | セル6 |
```
注意: ヘッダ行は末尾に `|h` を付ける。マークダウンの `|---|` 区切り行は **不要**(書くと崩れる)。
## 9. 画像
```
#image(添付ファイル名.png)
```
## 10. 水平線
❌ 水平線（----）は使用しない。見出し（* / ** / ***）で構造を区切ること。
## 11. 課題リンク(オートリンク)
プロジェクトキー + 番号(例: `WF-123`)はそのまま書けば自動でリンクになる。
明示的に書く必要なし。
## 12. 改行・段落
- 段落区切り: 空行を1行入れる
- 強制改行: そのまま改行(マークダウンのような末尾スペース2つは不要)
---
## 整形時のセルフチェック
本文を生成し終わったら、以下のパターンが残っていないか確認すること:
- [ ] `#` で始まる行がない(見出し残留)
- [ ] `**xxx**` `*xxx*` が本文中にない(強調残留)
- [ ] ` ``` ` が本文中にない(コードフェンス残留)
- [ ] `[xxx](yyy)` 形式のリンクがない(リンク残留)
- [ ] `|---|` 形式の表区切り行がない
1つでも残っていたら整形が不完全。やり直す。
---
## 構造化のヒント(任意)
ユーザーが要点を箇条書きで渡してきた場合、以下の構造に整理すると読みやすい:
```
* 概要
要点を1〜2行で。
* 詳細
- 項目1
- 項目2
* 期待される結果 / 受け入れ条件
- 条件1
- 条件2
```
ユーザーが具体的な構造を指定している場合はそちらを優先。
おわりに
今回のキモは rules/ の自動ロードを避けつつ、CLAUDE.mdに「該当タスクが来たら docs/ のファイルを読め」というディスパッチを書く ことで、 必要な時だけルールを効かせる設計 を組んだ点です。これを知らないと、ルールを増やすたびに無駄にコンテキストを食う構成になりがちです。
きっかけはBacklogの起票崩れでしたが、この設計パターンは 「特定タスクの時だけClaude Codeに特定のルールを意識させたい」 というニーズ全般に応用できます。たとえば:
- Slack投稿時に絵文字や改行ルールを守らせたい
- コミットメッセージをConventional Commits形式で書かせたい
こういった要件は CLAUDE.mdで全タスクに常駐させる必要はない ものばかりで、オンデマンド方式が向きます。
同じように「Claude Codeに条件付きでルールを効かせたい」「ルールが増えてきてCLAUDE.mdが肥大化している」と感じている人の参考になれば嬉しいです。