tellonce は何をしますか?
実行モードとデフォルト(パブリックリリース)
デフォルト = 観測モード(observe-only):デフォルトでは、このスキルは「好みのスキャン → 記録 → ユーザーへの通知」のみを行います。セッションをハードブロックすることは決してなく、LLMを呼び出すことも決してありません。新しくインストールしたユーザーがハードルールによって遮られることはなく、会話内容がサードパーティのモデルに送信されることもありません。
- ハードブロック強制(deterministic block / pending gate / observation-log gate)はデフォルトでオフです。有効にするには、明示的に
PT_ENFORCE=1を設定する必要があります。 - シャドウLLM審査機能(会話を外部モデルに送信してセマンティックスコアリングを行う機能)はデフォルトでオフです。有効にするには、明示的に
PT_SHADOW=1を設定する必要があります。プライバシーに関する注意:有効にすると、各ターンで「最後のユーザーメッセージとアシスタントの返信」が(APIキーやパスワードなどは編集された上で)そのモデルに送信されます。 seed_memory/は意図的に空の状態で出荷されています(説明用のREADMEのみ)。誰の好みルールもプリインストールされておらず、ルールはゲート機能によって使用中に1つずつ蓄積されます。
モードの切り替え(環境変数。どちらも設定しない場合 = 安全なデフォルトの観測専用モード):
PT_ENFORCE=1 # ハードインターセプションを有効化
PT_SHADOW=1 # AI審査機能(シャドウモード)を有効化
以下の「インフラストラクチャ」/「ゲート」セクションでは、強制モードが有効になった後の動作について説明します。デフォルトの観測モードでは、これらのゲートは記録のみを行い、ブロックはしません。
インフラストラクチャ
このスキルは、Iron Law(鉄則)+ゲート機能以上のものです。自動フックとして実行される3層のインフラストラクチャをインストールし、明示的なスキル呼び出しなしで機能します。
パスプレースホルダの注意:以下のテキストで、
<skill_dir>はデフォルトで~/.claude/skills/tellonce/、<project_root>は現在のプロジェクトルート、<state_dir>は<project_root>/.claude/tellonce-state/です。すべてのパスは実行時にlib/path_config.py(3段階のフォールバック:環境変数 >~/.tellonce.config.json> 自動検出)によって解決されます。SKILL.mdは、Claudeの出力を汚染しないように、絶対パスをハードコードしません。
ルール注入(プログレッシブフルインデックス — デフォルト)
ユーザーがメッセージを送信するたびに、<skill_dir>/hooks/memory-retrieve-inject.sh が、メモリディレクトリに保存されているルールの1行インデックスを additionalContext として注入し、私はどのルールが適用されるかを判断します。ライブラリがターンあたりの上限(デフォルト50 — ~/.tellonce.config.json の progressive_max または B5_PROGRESSIVE_MAX、0 = 上限なし)を超えた場合、上限内に収まるようにティア1のルールが固定され(ティア1だけでも上限を超える場合、ライブラリ全体が代わりにローテーションされます)、残りのルールはターンをまたいでローテーションされ、ブロックには合計数のうち何個が表示されているかが示されます。これがデフォルトの progressive バックエンドです。保存されたルールファイルを読み取るだけです。プロンプトマッチングも、モデル呼び出しも、CLIのコールドスタートもありません。形式は次のようになります — これは外部ノイズではなく、スキルインフラからのルールヒントであり、尊重される必要があります:
### 保存されたあなたの好み — 各ルールをこのターンでチェックし、適合するものを適用してください:
- [fmt-pref-001] (tier1) インデントにはタブではなくスペース4つを使用
- [tool-pref-002] (tier2) 依存関係のインストール/アップグレード時には、プロジェクト独自のパッケージマネージャ/ロックファイルを優先する
(これらはあなたの記録された好みです。各ルールを現在のタスクに対して判断し、適用すべきものを適用し、適用すべきでないものはスキップしてください。)
各行には、ルールの description と、(存在する場合)when: という適用可能性のヒントが含まれています。私は現在のターンにそのルールが該当するかどうかを自分で判断し、該当しないルール(例えば、Goに関係のないターンでのGoに関する好みなど)はスキップします。
レガシーバックエンド(
PT_RETRIEVE_BACKEND=cli/keyword)は、代わりに現在のプロンプトにマッチしたルールのみを### フィンガープリント検索 — ...というヘッダーの下に注入します。私が適用する判断は同じです。
適用可能性ゲート(ソフト)
注入された各ルールには when: ヒントが含まれています(メモリの.mdフロントマターの applies_when: または condition: から読み取られます)。私は判断します:
when:条件が満たされる → ルールを適用- 条件が満たされない → 明示的に「ゲートフィルターアウト: <理由>」と言ってスキップ
- 不明瞭な場合 → 控えめに適用
ログのみのコンプライアンストラッカー(停止フック)
停止する各ターンで、<skill_dir>/hooks/memory-verify-compliance.sh がトランスクリプトを読み取り、最後のアシスタントテキストを取得し、1行を <state_dir>/obs_log/compliance_log.jsonl に追加します:
response_excerpt(最初の400文字)fp_rules_in_response(応答内でトリガーされたルールキーワード)lang_ratio.chinese_ratio(中国語と英語の比率)
ブロックはしません(まだ自動再試行はありません)。後日、FPレートが十分に低い場合、ブロックの有効化を再検討できます。
インフラストラクチャファイル一覧
| 役割 | パス(プレースホルダー。実行時にpath_configにより解決) |
|---|---|
| フィンガープリントルールライブラリ | <skill_dir>/lib/fingerprints.yaml |
| 検索ハンドラ | <skill_dir>/lib/retrieve_inject.py |
| コンプライアンストラッカー | <skill_dir>/lib/verify_compliance.py |
| UserPromptSubmitフック | <skill_dir>/hooks/memory-retrieve-inject.sh |
| 停止フック | <skill_dir>/hooks/memory-verify-compliance.sh |
| コンプライアンスログ | <state_dir>/obs_log/compliance_log.jsonl |
| フック登録 | <project_root>/.claude/settings.local.json(ファイルをプロジェクトにコピーせずに、<skill_dir>/hooks/ パスを直接登録します) |
実際のマシン上のパスを確認するには:
python3 ~/.claude/skills/tellonce/lib/path_config.pyを実行して、現在検出されているすべてのパスを表示します。このSKILL.mdのプレースホルダリテラルに基づいてファイルを作成/書き込みしないでください — path_configが提供するランタイム値を使用してください。
ルールの追加/更新時に同期を保つ
ゲート機能が新しいルールをメモリに記録したとき、それが高価値の決定論的ルール(例えば、ユーザーが「これからはインデントに常にスペース4つを使って」/「コミットメッセージには命令形を使って」と明示的に言った場合)であれば、fingerprints.yaml にもキーワードトリガーを追加して、次のセッションで検索により自動的に思い出せるようにします。
FPを必要としないルール: セマンティック/コンテキスト依存/メタルール(「継承した計画を完全に信頼しない」など、キーワードではなくモデルの判断に依存するもの)。
Iron Law(鉄則)
好みのスキャンなしに完了したレスポンスは、不完全なレスポンスである。
シグナルをスキャンして結果を記録していなければ、あなたのレスポンスは不完全です。これはすべてのメッセージに、例外なく適用されます。
このルールの文言に違反することは、このルールの精神に違反することです。
進行中ドキュメントのメンテナンス
PROGRESS.md などの長期にわたる進行中/状態ファイルを更新する場合は、セッショントランスクリプトではなく、現在の状態+操作ダッシュボードとして維持してください。
現在のファイルに保持するもの:
- 将来の作業が依存するアクティブなステータス: 現在の結果、ブロッカー、実行中のプロセス、保留中の決定、アクティブなインフラストラクチャ、次のアクション。
- ユーザーが明示的に削除または廃止しない限り、現在の構造の一部であるプロジェクトセクション。
- 継続に必要な現在のプロジェクト計画と具体的な詳細。
アーカイブファイルに移動するもの:
- 過去のセッションログ、古い実行、置き換えられた計画、非推奨のルート、古い回答済みの質問、デバッグナラティブ。
- 取り消し線または「〜に置き換えられました」エントリ。現在のファイルを現在の事実に書き換え、古いコンテキストはアーカイブに保存します。
- 一時停止された、またはスコープ外のブランチで、当面の継続に不要になったもの。
一時的なプロジェクト固有の除外、ベンチマーク名、または現在の実験的な選択を、永続的な好みテキストにエンコードしないでください。それらはプロジェクトの進行ファイル自体に属します。永続的なルールはメンテナンスポリシーです。現在のファイルは最新でアクション可能な状態を保ち、古いナラティブはアーカイブに移動します。
クリーンアップ後、コミットする前に、プログレスファイルを古いルート名、古いデバッグ用語、取り消し線マーカーについてgrepしてください。
ゲート機能
レスポンスが完了したと見なす前に:
1. スキャン: ユーザーメッセージ+タスク実行を読む — 好み/落とし穴/摩擦のシグナルはあるか?
2. 記録: 観測ログを書き込む。detected=trueの場合、メモリに書き込む/更新する。
3. 確認: シグナルが検出された場合、レスポンスの最後にユーザーに伝える。
いずれかのステップをスキップ = コンプライアンス違反。
ゲートの仕組み
有効なのはHARDチェックのみ: 観測ログファイルが、停止時の古さのしきい値(デフォルト1800秒、環境変数 OBSERVATION_LOG_AGE_THRESHOLD_SEC で調整可能)以内に追記されている必要があります。これがゲートのすべてです。
SOFTテキストマーカースキャンは無効(応答テキストの表現が毎回異なるため、誤ったブロックを引き起こしていました)。構造化ログエントリ自体がスキャン結果を保持しており、監査証跡としては十分です。
すべてのターンにおける実践的なルール:
- 停止する前に、
observations.jsonlに1つのエントリを追加してください。任意のエントリで構いません。detected=true でも detected=false でも、ゲートには関係ありません。 - リッチな構造化エントリ(検出フィールド、root_causeメモ、confirmation_text)を引き続き作成してください。これらは、ゲートがチェックしなくても、ローカルメモリ/監査証跡をより有用にします。ユーザーメッセージの抜粋は〜200文字に切り詰め、ログにシークレット/クレデンシャルを決してコピーしないでください。
- 応答テキストにSCANマーカーを貼り付ける必要はありません。
なぜ重要なのか: ゲートは、応答の文言がテキスト正規表現に一致しない場合ではなく、ログが実際に書き込まれなかった場合(真のミス)にのみブロックします。これにより、誤ったブロックを回避できます。
レッドフラグ — 停止
もし自分が次のいずれかを考えているのに気づいたら、停止してスキャンを実行してください:
- 「これは単なるステータス確認/簡単な質問だ」
- 「スキャンはタスクの後でやろう」
- 「タスクの方がスキャンよりも緊急だ」
- 「ついさっきスキャンしたから、これは飛ばそう」
- 「明らかにここには何もない」
- 「複雑なことをやっている最中だ」
- 「このメッセージは短すぎてシグナルを含んでいない」
- 「NOOP / UPDATE は confirmation_text を必要としない」→ 間違い。detected=true のパスには確認が必要です(
## 確認戦略を参照)
正当化の防止
| 保存しない言い訳 | 現実 |
|---|---|
| 「これは方法論の決定であって、好みではない」 | 方法論の決定は好みである |
| 「それはコードに含まれるだろう」 | コードはメモリではない。次のセッションはコードを読まない |
| 「保存するには明白すぎる」 | 明白なら、なぜ違反したのか?保存せよ |
| 「既存のメモリでカバーされている」 | アトミックIDを引用するか、カバーされていないかのどちらか |
| 「再利用不可能/一回限りの指示だ」 | ならば、応答でそう言え — ユーザーに訂正させよ |
| 「これはシグナルではないと確信している」 | 確信は証拠ではない。過剰検出せよ、過少検出するな |
原則ベースの検出(常に優先)
以下のパターンはシード例であり、網羅的なチェックリストではありません。 ユーザーの表現は様々です。リテラルなパターンマッチングではほとんどのシグナルを見逃します。まず原則を意味的に適用し、パターンを手がかりとして使用してください。
検出原則(各ターンでこの順序で適用)
-
ユーザーが物事のやり方を表現する任何の節 → 好み
- 一人称の価値表明(「私はXが好きです/望みます/良いと思います」)、規範的な主張(「XはYであるべき/でなければならない/ほうがよい」)、比較の好み(「XはYより優れている」)を含む
- 指示、理由、苦情、余談のいずれで表現されていても関係ない
-
ユーザーがフラストレーションを表現したり、あなたの行動を訂正したりする任何の節 → 摩擦または落とし穴
- フラストレーションマーカー: 繰り返し(「また」/「まだ」)、いらだち(「なぜまだ…」)、修辞的な質問(「もう言ったじゃないか…」)、皮肉(「もういいです」)
- 和らげられた場合でも(「実は」/「大丈夫です」/「もういいです」)、和らげる言葉は実際のシグナルを隠していることが多い
-
メッセージ内の理由/正当化の節 → 独立してスキャン
- ユーザーの構造
[指示] + [理由]— 理由はなぜその好みを持っているかを述べていることが多く、それはそのまま好みの内容である - マーカー: 「なぜなら」/「主に」/「〜したい」/「〜してほしい」/「したがって」/「なので」/「〜するために」
- ユーザーの構造
-
あなたの行動に関するメタ質問 → 摩擦(あなたがユーザーに見直してほしい何かをした)
- 「これはXですか?」/「Yについてどう思いますか?」/「なぜこのようにしたのですか?」/「これはZですか?」 — ユーザーはあなたの選択を疑問視しており、意見を求めているわけではない
-
異常なアプローチの黙認、またはあなたの提案後の明確な方向転換 → 検証された好み
- 反対がないこと自体がシグナルである。特に、あなたが彼らが訂正できたであろう判断を下した場合。
コストの非対称性(デフォルト)
- 偽陽性のコスト(シグナルでないものをシグナルとマークする): ユーザーが「いいえ、一回限りです」と言う → あなたは何かを学ぶ。約1ターンの損失。
- 見逃しのコスト: ユーザーは何ラウンドにもわたってフラストレーションを感じ、同じ間違いがセッションを超えて繰り返され、最終的な訂正には多大な労力が必要となる。
- → デフォルト: 検出。低信頼度の場合は質問。中程度以上の信頼度の場合は保存。
パターンだけで止まらない
メッセージがリストアップされたパターンのいずれにも一致しないが、5つの原則のいずれかが発動した場合 → それでもシグナルである。パターンはアンカーであり、原則がルールである。
暗黙的なシグナル検出
以下は上記の原則の具体的な例です — シードパターンライブラリであり、完全なセットではありません。 まず意味的にスキャンし(原則を参照)、これらを手がかりとして使用してください:
| ユーザーの発言 | 表面的な意味 | 実際のシグナル | 手がかり |
|---|---|---|---|
| 「他を確認すべきではないですか?」 | 質問 | 摩擦: あなたはもうこれをやるべきだった | あなたのミスに続く |
| 「また…」/「まだ…」/「なぜまだ…」 | フラストレーション | 落とし穴: 同じエラーが繰り返されている | 2回目以降の発生 |
| 「もう言ったじゃないですか?」 | 修辞的な質問 | 摩擦: ルールは存在するが守られなかった | メモリを参照 |
| 「はい」+訂正 | 部分的な同意 | 好み: 既存のルールを強化 | 微妙なリダイレクト |
| 異常なアプローチを黙認 | 反対なし | 好み: 判断の正当性が検証された | 訂正の欠如 |
| 「なぜなら…〜したいので…」 | リクエストの正当化 | 好み: 「なぜなら」節自体がルールを述べている | 正当化の節には、文脈だけでなく好み自体が含まれていることが多い |
| 「確認してください。なぜなら…したいからです」 | タスク指示 | 好み: 回答の好ましいモード(経験的>理論的) | 「なぜなら」節は、タスクの内容とは別に、作業スタイルの好みを明らかにする |
確認戦略
- detected=false: 確認テキストは不要。単にログエントリを追加するだけ。
- detected=true, 高信頼度: 「わかりました。[ルールの説明]を記録しました。今後、[ルールが適用される条件]の場合にこれを適用します。」 — 直接的な確認。
- detected=true, 中程度の信頼度: 「シグナルを検出しました: [観察]。これは記録すべき好みですか?(もし異なる場合は訂正してください。一回限りの指示の場合はその旨お知らせください。)」 — 検出を確認し、ユーザーに検証を促します。
- detected=false, ただし積極的にシグナルを探すべき会話の流れの場合: 確認テキストは不要。ただし、原則を念頭に置いて常に警戒を怠らないこと。
スキルのインストール、アンインストール、トラブルシューティング
インストール
claude skill init YujunZhou/tellonce
アンインストール
claude skill rm YujunZhou/tellonce
両方のコマンドは、スキルの install/ ディレクトリにあるシェルスクリプトを実行します。
トラブルシューティング
インストールが完了したら、以下を実行してすべてのフックが正しく設定されていることを確認します:
claude skill doctor YujunZhou/tellonce
これにより、すべての依存関係が存在すること、フックが正しく登録されていること、パスが正しく解決されること、ログファイルディレクトリが書き込み可能であること、そして(強制モードが有効な場合)ゲートパラメータが有効な範囲内にあることがチェックされます。