Motoki is a tool that helps you work with AI agents.
エージェントが同じ誤りを繰り返す箇所を、次に起きないように直す。 人が直したときは、同じ手順を繰り返す。/correct のときに使う。
# correct
人が同じ誤りを何度も直しています。次のエージェントが同じ誤りをできないように、リポジトリを変えます。
見るのは開いたファイルだけです。1つのファイルから見て正しそうな変更が、リポジトリ全体でも正しいようにします。
## Step 1. ミスの分類を特定する
まず、直近のコミット、リバート、レビューコメント、エージェント向け指示ファイル、回避策を説明したコメントを確認してください。ミスをカテゴリごとにグループ化します。同じミスが2回発生した時点で、1つのクラスとしてカウントします。
## Step 2. 上から試し、通る段で直す
1. アーキテクチャによって排除する: 各状態の所有者を1つに絞り、各タスクのサポートされる手順を1つに限定する。誤ったインポートがエラーになるよう内部仕様を隠蔽してください。手動で同期しているリストは単一の信頼できる情報源（Source of Truth）に置き換える。エージェントがコピーしてしまわないよう、古い手法やデッドコードは削除してください。
2. 型定義で強制し、不正な状態を作成不可にする: 不正なコードがコンパイルを通ってしまう場合は、リンターやCIチェックを追加し、代わりに使うべきファイル・型・関数名をエラーメッセージ内で提示してください。すでに不適切なパターンが広がっている場合は、変更によって新規追加された場合のみエラーにしてください。
3. 振る舞いをテストする: 呼び出しているすべての関数が何も返さなくなったとしても合格してしまうようなテストは、修正するか削除してください。
4. ドキュメントやエージェント用ルールは最後（判断が必要な事項のみ）にする: エージェントが読み飛ばしてもエラーで検知できないため、過度に依存しないでください。
## Step 3. 修正と検証
最も頻繁に発生しているカテゴリから順に、1コミットにつき1クラスずつ修正してください。
新しく作成したチェック機構が、過去の実際のミスに対して正しくエラーを吐く（失敗する）ことを証明してください。
ローカル環境とCI環境の両方で同じ検証コマンドを実行します。
例外を認める場合は、該当する行に「理由」を明記してください。
## Step 4. ルールテーブルの維持
最後に、各ルールとそれを強制する手段をペアにしたテーブルを、エージェント用指示ファイル内で維持してください。
オペレーターから修正を指示されたら、そのミスを修正した上でルールを追加します。すでにルールが存在していたにもかかわらず強制手段がなかった場合は「再発」とみなし、同じ変更内でより高いレベルの修正を実施してください。
構造的にミスが発生し得なくなったルールはテーブルから削除します。
## Step 5. 出力
各カテゴリについて、エビデンス、採用した修正レベル、および「なぜより高いレベルの修正が適用できなかったのか」の理由を提示してください。難しいタスクのあと、同じ判断を次も間違えないように既存のスキルを1つ修正するときに使う。
# grow-a-skill
難しいタスクのあと、教訓を既存のスキルに反映する。
## 原則
- 一度きりのみのノウハウ、既存スキルでカバーできているものは入れない
- 残す文は、次回の判断を変えるものだけ。変更理由の記述は不要
- 編集先は既存のスキル1つだけ。一行か、短い文章の編集のみ
- 他のスキルに同様に本文がある場合は、繰り返さず参照させたいスキル名を示す
- 当てはまるスキルが無ければ、編集先が無いと書いて止め、ユーザーに新しいスキルを作成するか確認する
- 修正した本文をチャットに送信するどうやってこの機能を実現したのかを説明する。ユーザーが「Xはどのように機能しますか」という質問をしたときに使う。
# why
コードベースを調べて、「Xはどのように機能しますか」という質問に答える。
シニアエンジニアのレベルでアーキテクチャの解説を作成します。
## Step 1: 質問の理解
ユーザーが質問していること分析し理解します。
ターゲットが曖昧な場合は、会話のコンテキスト(開いているファイル、最近の編集履歴、カーソルの位置、今の会話内容)から最善に推測します。その後、ユーザーに推測した内容を確認して、修正するか確認します。
## Step 2: 探索
ユーザーの質問を2~4の探索項目に分割します。探索項目ごとにサブエージェントを並列で起動し、調査を開始します。
各サブエージェントは次のプロンプトを使用します。
```text
## ユーザーの質問
> {ユーザーの質問}
## あなたの探索項目
> {あなたの探索項目}
## 探索手順
1. エントリーポイントを見つける
2. 流れをたどる
3. 主要な関数やクラスを理解する
4. 境界線を見つける
全体像を説明できるようになるまで、探索を続けてください。追跡できない部分にぶつかった場合は、明示的にそう言ってください。
## 出力形式
調査結果をこの構造で返します。
## コンポーネント
主要なタイプ、サービス、クラス、抽象化、それぞれについて:名前、ファイル パス、およびその機能の1文の説明を書きます。
## 流れ
実行フローを段階的に説明します。
各ステップについて: どの関数/メソッドが実行されるか、どのファイル内にあるか、何を実行するか、次に何を呼び出すか。ステップ間を流れるデータを含めます。
## ファイル 読み取り
探索中に読んだすべてのファイルを列挙します。
## 境界
このサブシステムがコードベースの他の部分に接続する場所と、その入力と出力を書きます。
## 質問
調査で分からなかったことを正直に書きます。
```
## Step 3: 結果の集計と出力
調査した内容を可能な場合はビジュアライズ(Canvas, Artifacts等を使用)して、ユーザーに提示します。ビジュアライズできない場合はテキストで返します。
読みやすさと理解のために、サブエージェントが調査した内容を軽く修正してもよいです。motoki の仕事の入口。頼まれごとを平易な言葉に言い直してから、理解、案の比較、変更、レビュー、文書、PR、既存スキルの更新のどれへ渡すかを決める。motoki mode、/motoki-mode、この手順で仕事をする、と指定されたときに使う。雑談には使わない。
# motoki-mode
これは仕事の入口です。依頼がどの作業に当てはまるかを決め、そのスキルを開いて本文に従います。本文を読まずに手順を作ってはいけません。返信に書く名前は、この会話で開いたスキルだけです。複数の作業に当てはまるときは、理解、変更、文書の順に進めます。
## 進め方
1. Slack、Notion、PRのやりとりでは、頼まれごとと、それ以外の話を分ける。頼まれごとを、自分の平易な言葉で言い直してから動く。言い直しが依頼と違っていれば、作業の前に直す。
2. 先に、何が終わるかを言う。実装の手順は、その時点では決めない。
3. やり直せる作業は、確認を待たずに進め、結果を見せる。やり直せない作業は、人が決めるまで止める。対象は、本番の削除、メッセージの送信、force-push、破壊的なapplyなどである。
4. 目指す方向は人が決める。やり直せる実行は、確認のために止めない。進め方を聞かれたら、自分の判断を言う。不要な仕事は、不要だと言う。
5. どの案にするか、どう作るか、何をすべきかを人に聞く前、質問の種類を分ける。読むだけで分かる質問は`how`か`why`で答え、実装はしない。実行すれば分かる作り方は`parallel-option`で比べる。実験では決まらない好みや方針だけを、人に聞く。
6. 画面や見た目のデザインを決めるときは`parallel-design`を使う。
7. 返信は日本語で書く。書き方は`stop-ai-slop`に従う。
## 2. まず理解する
「どう動くか」「なぜそう書いたか」「これでよいか」を聞かれたときは、まだ変えません。
1. 処理の流れ、どのコードが持っているか、どの層にあるかは、`how`で説明する。
2. なぜそう書いたかを説明するときと、その選択を信じてもらうときは、`why`も使う。何を得て、何を失うかは一言で書く。同じ前提で二度失敗していたら、その前提を疑う。
3. このあとコードを変えるなら、「変える」に進む。
## 3. 変えるとき
機能を足すとき、不具合を直すとき、動きを変えずに構造だけ変えるときです。
1. 頼まれごとを言い直し、何が終わるかを先に言う。
2. 変える前に、`how`で今の動きを確認する。選択を信じてもらう必要があるときは`why`も使い、何を得て何を失うかを一言で書く。
3. 実装の形が決まっていないときは`parallel-option`を使う。関数をまたぐ設計が決まっていないときも同じである。案の数と、試作の消し方は、そのスキルの手順に従う。
4. 同じ操作をやり直すときは、二度目も一度目と同じ状態で終わるようにする。壊す操作は、先にdry runで確認する。
5. サブエージェントの個数と、見る観点は、開いたスキルに従う。返ってきた結果は自分で読み、自分の言葉でまとめる。
## 4. 書くとき
README、ドキュメント、RFC、PR、報告を書くときです。
1. テクニカルな文章は`technical-writing`で書く。
2. 日本語の言い回しは`stop-ai-slop`で確認する。メッセージの下書きも同じである。
3. 日本語の校正は`textlint-ja`で検査する。
## 5. PRを開くとき
CI、レビュー、マージの準備を見てほしいと頼まれたときだけ、`pr-watch`を使います。PRを開いただけでは始めません。マージは、頼まれたときだけ行います。
## 6. スキルを育てるとき
難しい仕事のあと、同じ判断を次も間違えないように残すは`grow-a-skill`を使います。
直すのは既存のスキル1つです。一度きりの出来事には使いません。
新しいスキルが必要なときは、作成前、ユーザーに確認します。>-
# notion-style
Notionページを作成、更新するときに設定するスタイル。
## Step 1: 対象
作成または更新するNotionページの本文に適用します。
他人が書いたページは、スタイルの調整を頼まれたときだけ対象にします。
## Step 2: 見出しの変換
参考となる元のMarkdownがある場合は、次の表で対応させます。
| Markdown | Notion |
| --- | --- |
| H1 | タイトル |
| H2 | H1 |
| H3 | H2 |
| H4 | H3 |
| H5 | H4 |
## Step 3: カラー
- 見出し1: その節を表す絵文字を先頭に付ける。背景は`{color="orange_bg"}`にする。既に絵文字があるときは足さない
- 見出し2: 文字色を`{color="orange"}`にする
- 見出し3: 文字色を`{color="gray"}`にする
### 例
```markdown
# 📌 これは見出し1です {color="orange_bg"}
## これは見出し2です {color="orange"}
### これは見出し3です {color="gray"}
#### これは見出し4です
```
`📌`は例。節の内容に合う絵文字を付けます。全ての節でユニークな絵文字にします。
## Step 4: 確認
適用後に、文言と、画像、動画、ファイル等が変わっていないことを確認します。デザインの方向性を複数検討します。ユーザーが明確なデザイン案を示さなかった場合には、このスキルを起動します。
# parallel-design
様々な角度からデザイン案を複数ユーザーに提示し、デザインの制作を補助する。
## Step 1: 内容の理解
ユーザーが尋ねているものを分析します。
ターゲットが曖昧な場合は、会話のコンテキスト(開いているファイル、最近の編集履歴、カーソルの位置、今の会話内容)から最善の推測をします。その後、ユーザーに推測した内容を確認して、修正するか確認します。
## Step 2: 既存デザインの確認
現在のアプリケーションのデザインから大きく外れるものは採用されにくいです。そのため、既存のデザインを確認します。
## Step 3: デザイン案の検討
どのような方向性のデザインが良いか10個検討します。
## Step 4: デザイン案の選択
デザイン案を10個検討した中から、ユーザーの意図に添いそうなものを3~5個選びます。
## Step 5: デザイン案の実装
デザイン案を選択したら、そのデザイン案でデモンストレーションを実装します。
実際に該当のソースコードから実装しても良いし、簡素化のためにHTMLで実装しても良いです。
ユーザーがデザインを確認しやすいように、スクリーンショットや、動きが関連するものは動画を撮影し添付します。
案A、案Bのように、ユーザーが選択しやすい名前にします。
## Step 6: デザイン案の評価
ユーザーに選択したデザイン案を確認し、フィードバックを受け取ります。
## Step 7: デザインの発展
ユーザーが選択したデザインに対し、微修正してさらに方向性を検討できるものがあれば、そのデザイン案を検討します。
ユーザーに選択肢を確認し、検討を続けるかどうかを確認します。
続ける場合は、Step 5から続けます。
## Step 8: デザインの決定
ユーザーに選択したデザインを確認し、デザインを決定します。
決まったデザインで実装を開始します。
デモで作ったものは、不要になったら削除します。実装の形が決まっていないときに、構造の違う案を複数出して根拠で1つ選ぶ。どの方式にするか、関数をまたぐ設計、やり方を比べてから決めたいときに使う。
# parallel-option
1つに決める前、実装の形を比べます。画面や見た目のデザインでは使いません。
## Step 1: 内容の理解
ユーザーが尋ねているものを分析します。
ターゲットが曖昧な場合は、会話のコンテキスト(開いているファイル、最近の編集履歴、カーソルの位置、今の会話内容)から最善の推測をします。その後、ユーザーに推測した内容を確認して、修正するか確認します。
## Step 2: 今の構造を見る
今のコードの責務と境界を確認します。そこから大きく外れる案は、根拠がない限り採用しません。
## Step 3: 構造の違う案を出す
構造が違う案を、2つか3つ出します。名前だけの違いや、見た目だけの違いは案にしません。
## Step 4: 決め手を確かめる
決め手が、小さな試作やコマンドで分かるときは、それを作って結果を残します。結果で決まることを、人には聞きません。試作は、決定のあと消します。取り返しのつかない操作では試作しません。
コードの広い範囲を読む必要があるときは、案ごとに読み取り専用のサブエージェントを1つ出し、並列で検証します。狭い範囲のときは、そのまま比べます。サブエージェントの結果は、自分で読んでまとめます。
## Step 5: 1つに決める
根拠のある案を1つ選びます。選んだ理由と、捨てた理由を書きます。実験では決まらない好みや方針だけは、案を見せて人に選んでもらいます。
あなたが推奨する順番で案を並べます。
本実装は、このスキルの外で続けます。
## 出力
```markdown
## 決めたいこと
{決めたいこと}
## 案
### 案A
{案Aの内容}
- メリット
- デメリット
- 決め手：何を見れば、この案でよいか分かるか
- 根拠
## 推奨する案
名前と、選んだ理由。
```コードや文書を、正しさ、検証、安全の観点でレビューします。間違えがあっても、すぐ気づかなそうな変更があった場合に起動します。ただのリネームや、宣言箇所の変更など、中身に影響を与えない変更では起動しません。
# parallel-review
複数の観点でレビューします。
## Step 1:範囲と意図
差分、または指定されたファイルが対象範囲です。
まず変更の意図を短く書きます。意図が言えなければ、ユーザーに確認します。
## Step 2: レンズの選択
レビューする観点は次のとおり。
コードをレビューする場合と、ドキュメントをレビューする場合で分岐します。
### コードレビュー
コードをレビューする場合。
- Logic Review: 意図を理解し、実装、コマンドが正しく動くか。
- Test Review: 対象範囲のテストを正しく実装しているか。
- Security Review: セキュリティの観点から脆弱性がないか。
#### 各レンズをスキップする条件
- HTML、Terraformなど、ロジックがないものはTest reviewをスキップ
- iOSアプリ、LPなど、サーバー間とデータを連携しないものはSecurity Reviewをスキップ
軽微な修正（文言、リネーム等）の場合は、Logic Reviewのみを実行します。
### ドキュメントレビュー
ドキュメントをレビューする場合。
- Logic Review: 意図を理解し、論理の破綻がないか。数値の間違いがないか
- Writing Review: 文書の書き方が正しいか。誤字脱字がないか。テクニカルな文章はtechnical-writing skillを使用
- AI Slop Review: AIっぽい文章がないか。stop-ai-slop skillを使う
#### 各レンズをスキップする条件
軽微な修正（文言、リネーナ）の場合は、Writing ReviewとAI Slop Reviewのみを実行します。
## Step 3: レビュー
レンズごとにサブエージェントを読み取り専用で並列に起動します。
各サブエージェントは次のプロンプトを使用します。
```text
# {レンズ}
## 変更の意図
> {変更の意図}
## あなたのレンズ
> {あなたの探索項目}
## 参照するSkill
必要な場合だけ記述。
## 出力形式
調査結果をこの構造で返します。
## 指摘事項
1. {指摘事項1} (場所、何が悪いか、なぜか、直すなら何を)
## ファイル 読み取り
探索中に読んだすべてのファイルを列挙します。
## 質問
調査で分からなかったことを正直に書きます。
```
## Step 4: 結果の集計
サブエージェントが収集した情報を集計します。
### 出力形式
```text
## 変更の意図
> {変更の意図}
## レンズ
### {レンズ1}
- {指摘事項1}
## Step 5: Next Action
各サブエージェントが指摘した内容を総合し、何をやるべきか提案します。
```Pull Requestがマージできるかをチェックする。Pull Requestを作成したらこのスキルを起動します。
# pr-watch
CIの失敗、レビューの指摘、準備が揃っているかをチェックします。マージは、明示して頼まれたときだけ。
## Step 1: 質問
ユーザーに`AskQuestion` Toolを使用し、Pull Requestをwatchするかを尋ねます。
Yesと回答したら、Step 2に進みます。
Noと回答したら、スキルを終了します。
## Step 2: CIのチェック
`/loop 5m`でPull Requestの状況をチェックし、CIが完了するまで待ちます。
1時間チェックしても完了しない場合は、スキルを終了します。
CIが全てGreenになり、Approve待ちだけになったらStep 3に進みます。
Approveが不要なリポジトリは、Step 4に進みます。
## Step 3: Approve待ち
`/loop 30m`でPull Requestの状況をチェックし、Approveされるまで待ちます。
レビューで指摘があった場合は、修正します。判断が必要な場合はユーザーに確認します。
## Step 4: マージの確認
すべてが揃ったらユーザーにマージするかを尋ねます。
Yesと回答したら、Step 5に進みます。
Noと回答したら、スキルを終了します。
## Step 5: マージ
Pull Requestをマージします。
マージではなく、リポジトリのルールで別の反映手順があるときだけ、その手順で反映します。
マージが成功したら、スキルを終了します。
マージが失敗したら、ユーザーにフィードバックを返し、スキルを終了します。コードを実行できない環境で、日本語の文章をtextlint-jaと同じ基準で読み、指摘を直す。Notion AIのように、シェルでtextlintを実行できないときに使う。シェルでtextlintを実行できるときはtextlint-jaを使う。
# proofread-ja
コードは実行しない。この文書のルールで日本語を読み、指摘を直す。
意味は変えない。言い切りの強さは変えない。
言い回しの自然さはstop-ai-slopで直す。技術文書の構成はtechnical-writingで直す。
使えるときは、このスキルのあとでそちらに渡す。使えなければ、このルールだけを適用する。
## Step 1: 対象
ユーザーが指定した文章を読む。指定が無いときは、今編集している日本語を対象にする。
ファイルでも、貼られた文章でも、同じルールで読む。
## Step 2: 対象外
対象外のものは、次のとおり。
- コードブロック
- インラインコード
- URL
- HTMLコメント
### 文の形
- 一文は100字までとする。超えたら句点で分ける
- 読点「、」は一文に3つまでとし、超えたら文を分ける
- カンマ「,」は一文に3つまでとし、超えたら文を分ける
- 漢字が7文字以上続いたら、読めるように開くか語を分け、残すなら質問する
- 文として終わるところは「。」とする
- 見出しと、名詞で終える箇条書きには句点を足さない
- 括弧は、開いたら閉じる
- Markdownの記法は変えない
- 本文の文末は敬体に揃え、箇条書きの文末は常体に揃える 見出しは、見出しの中で揃っていればよい 本文と見出しの違いや、本文と箇条書きの違いは直さない
- 文の途中にある接続の常体は見ない
- 名詞で終わる箇条書きに、常体の述語は足さない
- 文章全体の調子を敬体に変えると意図が変わるときは、直さず質問する
### 数字
数えられる数量は算用数字にする。
慣用句、熟語、概数、固有名詞、副詞など、漢数字が一般的な語句は漢数字のままにする。
任意の数に置き換えても通じるものを、数えられる数量とする。
算用数字にする形は、次のとおり。
- 漢数字のあとに、回、か月、番目が続く形。`三回`は`3回`にする
- 漢数字のあとに、進法、次元が続く形も同じとする
- 漢数字のあとに、兆、億、万が続く形。`三万`は`3万`にする
- 「数十万」「数百億」のような概数は漢数字のままにする
- 漢数字のあとに「つ」が続く形。`三つ`は`3つ`にする。下の形は算用数字にしない
- 「第」のあとに漢数字と、章または節が続く形。`第三章`は`第3章`にする
「つ」で算用数字にしない形は、次のとおり。
- `一つ返事`
- `一つ子`
- `一つ星`
- `一つ編`
- `一つ葉`
- `一つ橋`
- `二つとない`
- `二つに一つ`
- `ただ一つ`
- `唯一つ`
- `女手一つ`
- `男手一つ`
- `穴一つ`
- `瓜二つ`
- `馬鹿の一つ`
`一つ返事`は、ここでは算用数字にしない。誤用の節では`二つ返事`に直す。
漢数字に戻す形は、次のとおり。
- `世界1` -> `世界一`
- `1時的` -> `一時的`
- `1部分` -> `一部分`
- `第3者` -> `第三者`
- `1種` -> `一種` (`1種類`や`11種類`はそのまま)
- `1部の` -> `一部の`
- `1番に` -> `一番に`
- `数10倍` -> `数十倍`
- `数10年` -> `数十年`
- `数10万` -> `数十万`
- `数100億` -> `数百億`
- `5大陸` -> `五大陸`
### スペース
- 半角と全角の間にスペースを入れない
- 全角文字どうしの間にスペースを入れない
- カタカナのあいだにある全角スペースだけを、中黒「・」か半角スペースにする
- 区切りの無い語には、中黒やスペースは足さない。
- 括弧の内側にスペースを入れない
- 括弧の外側にスペースを入れない
- スラッシュの前後にスペースを入れない
- インラインコードの前後にスペースは入れない
- リンクの前後にスペースは入れない
- 太字の前後のスペースは見ない
- 斜体の前後のスペースは見ない
- 全角の`！`の直後に半角スペースがあるときだけ、そのスペースを全角スペースにする
- 全角の`？`も、同じにする。スペースが無い文には足さない
- 半角の`!`と`?`は、この項では見ない
### 誤字
- 半角カナは全角にする
- 離れた濁点は、1文字に戻す。`ホ゜`は`ポ`にする。`シ゛`は`ジ`にする
- 改行とタブ以外の制御文字は消す
- ゼロ幅スペースは消す
- 日本語に挟まれた英字1文字は、入力ミスとする 全角英字も含む 2文字以上は見ない
- `a` `i` `u` `e` `o` `n`と大文字は残す 英単語、識別子、URLは残す
- 同じ単語が直後に2度続いていたら、誤入力として1つにする `どんどん`のような重ね言葉と、意図した反復は残す
- その他誤字があれば修正する 判断がつかないときは質問する
### 読みにくさ
- ら抜きは、らを戻す `見れる` -> `見られる` `来れる` -> `来られる` 五段の可能は残す（走れる、書ける）
- 二重否定は、読みにくければ1回の否定か肯定にする（例：`ないことはない`と`なくはない`）言い切りの強さが変わるときは、直さず質問する。
- 逆接の接続助詞を、同一文で2回以上重ねたときは、文を分ける 1回だけなら残す。
- 同じ接続詞で始まる文が続くときは、2つ目を変えるか削る（例：`しかし、しかし`）
- 同じ助詞がすぐ近くに重なるときは、取り違えなら助詞を直す 詰め込みなら文を分ける 判断できなければ質問する。（例：`私は彼は`）
- 次の重なりは残す
- 「を」の重なり
- 接続の「て」
- 並立助詞が2つある形
- 「〜かどうか」
- `AのBのC`
- 並列の「と」
### 冗長
省いても意味が変わらない言い方だけ、短くする。
- `することができる` -> `できる`
- `することが不可能` -> `できない`
- `であると言えます` -> 前半か後半の、どちらか一方にする
- `であると考えている` -> 前半か後半の、どちらか一方にする
- 「する」を付けて動詞になる名詞のあとが「を行う」や「を実行」なら、「する」にする
- `検討を行う` -> `検討する`
- `確認を実行` -> `確認する`
- `処理を行う` -> 残す
### 誤用
技術用語の取り違えと、崩れた慣用句を、決まった形に戻す。
意味が近い別の言葉には言い換えない。確信がなければ質問する。
技術文書で出るものは、次のとおり。
- 規則や設定を当てる語は「適用」とする。環境に合う語は「適応」とする
- `値を返却する` -> `値を返す` メソッドや関数の`返却値`は`返り値`にする
- `例外を補足` -> `例外を捕捉`
- `可変する`とは言わない。変える、変わる、可変にする、のいずれかを使う。
- 動詞に`ずらい`が続くときは`づらい`にする（例：`書きずらい` -> `書きづらい`）
慣用句は、その句として正しい形かを見る。辞書の全件は持たない。明らかな崩れだけ戻す
- `こんにちわ` -> `こんにちは`
- `固定概念` -> `固定観念`
- `絶対絶命` -> `絶体絶命`
- `一つ返事` -> `二つ返事`
- `似て異なるもの` -> `似て非なるもの`
### AIの定型
表現を縛らず、型だけ外す。
- 箇条書きの先頭を、太字のラベルと区切りで始めない。絵文字でも始めない。ラベルは地の文にする。区切りの例は`**ラベル**:`とする。
- 次の太字を外す 意味のための強調は残す
- 情報のラベル（注意、重要、ポイント、メモ）
- 参考、補足、確認、チェック
- 推奨、おすすめ、例、サンプル
- 絵文字と太字の組
- 見出しの中の太字
- コロンの前が動詞や形容詞で終わり、直後にブロックが続く型は、文を終えてからブロックを置く（対象：コード、リスト、引用、表）`手順:`や`例:`のように、名詞で終わるものは残す
- 売り文句は、事実として書ける範囲に直す その強さ自体が主張なら、直さず質問する
- 絶対や完全（例：`完全に`と`究極の`）
- 感覚（例：`魔法のように`と`奇跡的`）
- 予言や権威（例：`革命的な`と`ゲームチェンジャー`）
- `世界初の`と`パラダイムシフト`も同じとする
- `次世代の`と`不可避の`も同じとする
見ないものは、能動態への書き換えと、抽象語の数値化と、用語のゆれの統一とする。文の長さと冗長は、上のルールだけを見る
### 技術文書で加えるもの
- 感嘆符と疑問符は使わない
- 弱い表現は修正する 推量そのものが内容なら、直さず質問する
- `かも。`
- `かもしれ`
- `思う` -> `思います`
- `可能性を示唆している` -> `可能性がある`か`を示唆している`の、どちらか一方にする
## Step 4: チェック
修正後の文章を同じルールでもう一度読み、残りがないことを確認する。
## Step 5: 結果
```markdown
## 指摘
- ルール名: 元 → 後
## 残したところ（必要なときだけ）
- 残した文と理由
## 質問（必要なときだけ）
- 判断がつかなかった点
```AI生成や下書きの日本語を、言っていることは変えずAIっぽさだけ削って、自然な文にする。「読みやすくして」「AIっぽさをなくして」「自然な日本語にして」や技術記事・仕様/PR・レポート・Slack・エッセイの推敲時に使う。
# stop-ai-slop
言っていることは変えず、AIっぽさだけを削る。
分からないことは本文に書かず、確認事項にする。
## Step 1: textlint-ja
先にtextlint-ja skillを実行する。
## Step 2: 原則の確認
1. 意味の完全保持 — 主張・比重・言い切りの強さ・文の働きを変えない。足さない。分からなければ確認事項。
2. SVOCM — 文脈にある動作主・対象だけ復元する。指示語は指し先が分かるときだけ実名化する。
3. 擬人化だけ直す — 意志・感情を持たせた道具・概念は解体する。客観的な仕組みの主語はそのまま残す。
4. 比喩はふだんの言葉にし、含みは残す — 評価や気持ちの向きは別の平易な語で残す。慣用句は残す。
5. 前置き・否定対比は慎重に —「重要なのは」は述語へ移す。意味を担う「AではなくB」は肯定化しない。
6. 装飾を削る — 絵文字、em dash、冗長なカッコを除く。太字は1000字あたり2箇所以内、箇条書きは全体の15%を目安にする。
7. 読みの拍 — 平均30–45字、読点は0–2。同一文末が3連続したときだけリズムを調整する。1段落1話題。空の予告文は、その重みを述語に残して中身と統合する。
8. 水増しと比喩の重ね — 出典の無い「専門家は」「一般に」「よく言われる」は削るか、確認事項にする。もちろん、言うまでもなく、間違いなく、は削る。言い切りの強さは変えない。比喩は一文に重ねず、ふだんの言葉にする。
文末の種類（依頼・説明・断定・推量）は元のまま維持する。言い切りを推量に弱めたり、説明を可能表現に変えたりしない。
## Step 3: 文章の書き直し
原則に従って、文章を書き直します。
## Step 4: 結果の出力
```markdown
### 書き直した本文
（推敲した本文）
### 変えたところ
- 元 → 後（理由）。意味が動きやすい変更、つなぎ、補った語だけ。最大5件。なければ「なし」
### 残したAIっぽいところ（必要なときだけ）
- 意味や重みがあるので残した表現と、削るかの確認。なければ見出しごと出さない
### 書き手に確かめたい点（必要なときだけ）
- 判断がつかなかった点
```
## 語例カタログ
修正対応表。文字どおりの用法と、ふだんの慣用句は書き換えない。
| 元 | 自然な日本語 |
| --- | --- |
| 効く | 役に立つ、効果がある |
| 壊れる（データ・仕組み） | おかしくなる、使えなくなる |
| 倒す | 合わせる、選ぶ |
| 溶かす（時間など） | 費やす、かける |
| 潰す | なくす、直す |
| 踏み込む | 詳しく書く、中身に入る |
| 静かに | 気づかないうちに |
| 黙って | 知らないうちに |
| 解像度 | 具体さ、詳しさ |
| 腹落ち | 納得 |
| 重要なのは | 述語へ（〜が重要だ） |
| いかがでしたでしょうか | 削る |
書き換えない例: お握り、氷を溶かす、お腹を壊す。TDDを実施するためのskillです。リポジトリで最初の作業をおこなう時やユーザーがTDDを希望した時にこのskillを呼び出します。
# TDD
ここでいうTDDとは、Red/Green/Refactorの3つのステップを繰り返すことを指します。
## 環境構築
AGENTS.mdに次の内容を追記します。同じ見出しがあるときは、追記しません。
```markdown
## TDD（Red / Green / Refactor）
このリポジトリでは、機能追加・バグ修正・リファクタのすべてをRed → Green → Refactorで進める。テストを書く前に実装しない。
### 手順
1. Red: 失敗するテストを先に書く。実行して失敗することを確認してから実装に入る。
2. Green: そのテストを通す最小の実装だけを足す。先回りして別機能を足さない。
3. Refactor: テストが緑のまま、重複や不要なコードの削除、リーダブルな命名、構造を整える。挙動は変えない。
ステップごとにTestsを実行して、成功or失敗することを確認します。
```
## 実行
各ステップの終わりに、テストを実行します。成功か失敗かは、その出力で判断します。テストの削除、スキップ、期待の削除は、成功になりません。
テストの実行コマンドや手順は、リポジトリに書いてある手順を使います。
テストが1つもないリポジトリの場合は、このSkillを終了します。
## Step 1: Red
このステップで書くのは、失敗するテストです。
1. 要件を満たすために必要なテストを書く
2. テストを実行し、失敗することを確認する
動きを変えないリファクタだけのときは、失敗するテストを書きません。
## Step 2: Green
実装を追加します。
完了条件は、テストが成功することです。
基本的にはこのステップでテストを修正してはいけません。しかし、もしテストに明らかな不備がある場合は修正可能です。
## Step 3: Refactor
実装が完了したら、 parallel-reviewを呼び出します。
内容を確認して、必要な修正をします。
修正が完了したら再度テストを実行し、成功することを確認します。
## Step 4:出力
終わったら次の形式で出力します。
```markdown
## TDD
## Red
- テスト1：{テストの観点を一言で書く}
## Green
- テスト1の実行結果：成功
- テスト2の実行結果：成功
## Refactor
- Refactor 1：{整えたことを書く}
- すべてのテストの実行結果：成功
```マニュアルや提案書などロジカルな文章を書く、または直すときに使う。
# technical-writing
読み手が迷わず次の行動まで進める文に書き換える。日本語の言い回しはstop-ai-slop skillで確認する。
## Step 1: textlint-ja
先にtextlint-ja skillを実行する。
## Step 2: 原則の確認
主張・事実・言い切りの強さは変えない。文脈に無い期限や数値は足さず、ユーザーへ質問します。
- 核になる結論と、読み手にしてほしい行動を先に置く。起承転結にしない。主題に効かない段落と繰り返しを削る
- 一文一義。50字を超えたら割る。「〜ので」でつなぎっぱなしにしない。不要な接続詞は削る
- 口語は書き言葉にする（みたいな→のような、やっぱり→やはり、なので→そのため）
- 「など」は、具体例が文脈にあればその例にし、不要なら削る
- 操作の指示は能動の動詞、結果は受動。名詞で終える要求は、読み手の動作にする
- いつ・どこで・誰が・何を・なぜ・どのように・いくらでは、文脈にあるものだけ書く
- 3つ以上の列挙は箇条書きにし、7項目以内に収める。カタカナの長音と専門用語を文章内で1つに揃える
## Step 3: 文章の書き直し
原則に従って、文章を書き直します。
## Step 4: 結果の出力
```markdown
## 変えたところ
- 元 → 後（理由）
## 残したところ（必要なときだけ）
- 意味や意図を考慮し、あえて修正しなかったところ
## 質問
- 判断がつかなかった点。なければ見出しごと出さない
```日本語の文章をtextlintで検査し、指摘を直す。シェルでtextlintを実行できるときに使う。実行できないときはproofread-jaを使う。
# textlint-ja
日本語をtextlintで検査し、指摘を直す。
意味は変えない。言い回しはstop-ai-slop、技術文書の構成はtechnical-writingに従う。
シェルでtextlintを実行できないときは、proofread-jaを使う。
## Step 1: 対象
ユーザーが指定したファイルを検査する。文章を貼られたときは、一時ファイルに書いてから検査する。
指定が無いときは、今編集している日本語の文章を対象にする。
## Step 2: 実行
このスキルの`scripts/lint.sh`を実行する。
- プロジェクトにtextlintの設定があるときは、その設定で実行する。ルールは足さない。依存もプロジェクトには入れない
- 設定が無いときは、同梱の設定を使う。実行前に、同梱パッケージがレジストリの最新かを確認し、古ければ更新してから実行する。確認できないときと、更新に失敗したときは実行しない
- 通常: オプションなし
- マニュアル、README、仕様、提案、設計文書: `--technical`
- 漢数字と算用数字の使い分けは、通常も`--technical`も検査する
```bash
scripts/lint.sh path/to/file.md
scripts/lint.sh --technical path/to/manual.md
```
## Step 3: 修正
1. 指摘を読む
2. 同じオプションのまま`--fix`を付けて、機械的に直るものだけ直す。`--technical`を付けた検査なら、修正のときも付ける
3. `--fix`の残り件数は残件の全体ではない。本文を直す前に、`--fix`なしで一覧を取り直す。
4. 残ったエラーは本文を直す。意味、言い切りの強さは変えない
5. `--fix`なしで、同じオプションでもう一度実行し、エラーが残っていないことを確認する
固有名詞や引用で指摘が残るときは、ルールを消さない。残すかをユーザーに確認する。
同意があるときだけ`<!-- textlint-disable -->`を使う。
プロジェクトの設定ファイルは、頼まれたときだけ作る。
## Step 4: 結果の出力
```markdown
## 指摘
- ルール名: 元 → 後
## 残したところ（必要なときだけ）
- 残した文と理由
## 質問（必要なときだけ）
- 判断がつかなかった点
```なぜこのような実装をしたのかを説明する。
# why
なぜこのような実装をしたのかを、コードやドキュメントから参照し説明する。
## Step 1: 質問の理解
ユーザーが質問していること分析し理解します。
ターゲットが曖昧な場合は、会話のコンテキスト(開いているファイル、最近の編集履歴、カーソルの位置、今の会話内容)から最善の推測をします。その後、ユーザーに推測した内容を確認して、修正するか確認します。
## Step 2: 調査員の生成
調査するためのエージェントを生成します。このエージェントは、コードやドキュメントを参照し、ユーザーの質問に回答するための情報を収集します。
1. Source code investigator: Gitの履歴、`gh` Pull Request、コードコメント、ソースコードを確認する。
2. Ticket investigator: (例: Jira, Linear, GitHub Issues, Notion DB)チケットの説明、コメント、チケットの履歴を確認する。
3. Documentation investigator: (例： Notion, Confluence, Google Docs) ドキュメントから実装の根拠を探す。
4. Chat investigator: (例： Slack, Teams, Discord) 過去の会話から関連情報を収集する。
5. Infrastructure investigator: (例： Datadog, New Relic, Sentry) コードの動機となったインフラストラクチャとランタイム、エラーの状況を確認する。
### 調査員のスキップ
- MCPが利用できない場合は、その調査員をスキップします(例: Slack MCPが接続されていない)
- 無関係と思われる情報源はスキップする
## Step 3: 結果の集計
エージェントが収集した情報を集計します。
### 出力形式
```text
## 質問
ユーザーの質問。
## 結論
わかったことを簡潔に要約する。
## 参考資料
出典を添えて、結論の背景を説明する。
## 不明だったこと
情報不足、参照権限不足などにより、ユーザーの質問に答えられなかったこと。
```