Skip to content

Commit 95a6d7e

Browse files
eltocieareltociear
committed
docs: add Japanese translation of docs and update README-ja_JP.md links
- Translate all 9 English docs (docs/*_en.md) into Japanese (docs/*_ja.md) - Point README-ja_JP.md doc links to the Japanese versions
1 parent dcd3913 commit 95a6d7e

10 files changed

Lines changed: 1760 additions & 5 deletions

‎README-ja_JP.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ npm install -g @vegamo/deepcode-cli
4747

4848
この設定ファイルは [Deep Code VSCode 拡張機能](https://github.com/lessweb/deepcode) と共有されます — 一度設定すれば、どこでも使えます。
4949

50-
設定の詳細(多階層の優先順位、環境変数など)については、[docs/configuration.md](docs/configuration.md) を参照してください。
50+
設定の詳細(多階層の優先順位、環境変数など)については、[docs/configuration_ja.md](docs/configuration_ja.md) を参照してください。
5151

5252
## 主な機能
5353

@@ -110,7 +110,7 @@ Deep Code はマルチモーダル入力をサポートしています — `Ctrl
110110

111111
### タスク完了後に自動で Slack メッセージを送信するには?
112112

113-
Slack の Webhook を呼び出すシェル通知スクリプトを作成し、`~/.deepcode/settings.json` の `notify` フィールドにそのスクリプトのフルパスを設定します。詳細な手順は [docs/notify_en.md](docs/notify_en.md) を参照してください。
113+
Slack の Webhook を呼び出すシェル通知スクリプトを作成し、`~/.deepcode/settings.json` の `notify` フィールドにそのスクリプトのフルパスを設定します。詳細な手順は [docs/notify_ja.md](docs/notify_ja.md) を参照してください。
114114

115115
### Web 検索を有効にするには?
116116

@@ -135,17 +135,17 @@ Deep Code には、ほとんどのユースケースで十分に機能する無
135135

136136
Deep Code は MCP(Model Context Protocol)をサポートしており、GitHub、ブラウザ、データベースなどの外部サービスに接続できます。`settings.json` の `mcpServers` フィールドを設定して有効化し、`/mcp` コマンドで MCP サーバーの状態と利用可能なツールを確認できます。
137137

138-
詳細なセットアップ手順は次を参照してください: [docs/mcp.md](docs/mcp.md)
138+
詳細なセットアップ手順は次を参照してください: [docs/mcp_ja.md](docs/mcp_ja.md)
139139

140140
### タスク完了後に通知を送信するように Deep Code を設定するには?
141141

142142
AI アシスタントがタスクを完了すると、Deep Code は通知スクリプトを自動的に実行して、タスクの結果を指定されたチャネル(Slack、システム通知など)に送信できます。
143143

144-
詳細な設定手順は次を参照してください: [docs/notify_en.md](docs/notify_en.md)
144+
詳細な設定手順は次を参照してください: [docs/notify_ja.md](docs/notify_ja.md)
145145

146146
### Deep Code は YOLO モードのみのサポートですか?
147147

148-
いいえ。Deep Code にはきめ細かな権限制御メカニズムが組み込まれており、AI アシスタントがシェルコマンドの実行、ファイルの読み書き、ネットワークアクセスなどを行う前に操作を確認できます。`settings.json` の `permissions` フィールドで、各権限スコープのポリシー(常に許可、常に確認、拒否)を設定できます。詳細は [docs/permission.md](docs/permission.md) を参照してください。
148+
いいえ。Deep Code にはきめ細かな権限制御メカニズムが組み込まれており、AI アシスタントがシェルコマンドの実行、ファイルの読み書き、ネットワークアクセスなどを行う前に操作を確認できます。`settings.json` の `permissions` フィールドで、各権限スコープのポリシー(常に許可、常に確認、拒否)を設定できます。詳細は [docs/permission_ja.md](docs/permission_ja.md) を参照してください。
149149

150150
## コントリビューション
151151

‎docs/agent-skills_ja.md‎

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
# エージェントスキル
2+
3+
## 概要
4+
5+
スキルは、次のような指示セットに適しています。
6+
7+
- コードレビュー、リリース準備、レポート生成など、複数のタスクで繰り返し使うもの
8+
- 毎回プロンプトに貼り付けるには長すぎる、または詳細すぎるもの
9+
- テンプレート、スクリプト、スキーマ、サンプル、リファレンスドキュメントなどのリソースを伴うもの
10+
- 「PDFフォームを処理する」「このプロジェクトのデータベースマイグレーションを作成する」のように、明確な状況で発動するもの
11+
12+
次のような用途にはスキルを使わないでください。
13+
14+
- 一度きりのタスク要件
15+
- 短いリポジトリルール(通常は `AGENTS.md` に書くのが適切です)
16+
- 外部システムへのライブな操作(通常はMCP(Model Context Protocol)ツールが適切です)
17+
18+
## スキャン対象の場所
19+
20+
Deep Code CLIは以下の順序でスキルをスキャンします。複数のスキルが同じ `name` に解決された場合、最も優先度の高いものだけが有効になります。
21+
22+
| 優先度 | スコープ | パス | 用途 |
23+
| -------- | ------- | --------------------- | ------- |
24+
| 1 | プロジェクト | `./.deepcode/skills/` | Deep Codeネイティブのプロジェクトスキル |
25+
| 2 | プロジェクト | `./.agents/skills/` | 他のエージェントクライアントと共有するプロジェクトスキル |
26+
| 3 | ユーザー | `~/.deepcode/skills/` | Deep Codeネイティブのユーザースキル |
27+
| 4 | ユーザー | `~/.agents/skills/` | 他のエージェントクライアントと共有するユーザースキル |
28+
| 5 | グローバル | `built-in` | Deep Codeに同梱されているスキル |
29+
30+
構成例:
31+
32+
```text
33+
.deepcode/
34+
└── skills/
35+
└── code-review/
36+
├── SKILL.md
37+
├── checklist.md
38+
└── scripts/
39+
└── collect-diff.sh
40+
```
41+
42+
## 最小構成のスキル
43+
44+
各スキルは専用のディレクトリに置き、`SKILL.md` を含める必要があります。
45+
46+
```markdown
47+
---
48+
name: code-review
49+
description: Review code changes for correctness, regressions, security risks, and missing tests. Use when the user asks for a review, PR review, diff review, or pre-merge check.
50+
---
51+
52+
# Code Review
53+
54+
Use a code review mindset. Prioritize bugs, behavioral regressions, security issues,
55+
and missing tests over style comments.
56+
57+
## Workflow
58+
59+
1. Inspect the diff and relevant surrounding code.
60+
2. List findings first, ordered by severity.
61+
3. Include file and line references for every finding.
62+
4. If there are no findings, say so and mention residual risks or test gaps.
63+
```
64+
65+
## `SKILL.md` のフロントマター
66+
67+
Deep Code CLIは `SKILL.md` の先頭にあるYAMLフロントマターを読み取ります。
68+
69+
| フィールド | 必須かどうか | Deep Codeの動作 | 推奨事項 |
70+
| ----- | -------- | ------------------ | -------------- |
71+
| `name` | 推奨 | スキルの一意な名前として使われます。未指定の場合、Deep Codeはディレクトリ名を使い、`_` を `-` に変換します。 | 小文字、数字、ハイフンを使い、ディレクトリ名と揃えてください。 |
72+
| `description` | 推奨 | 自動マッチングに使われ、`/skills` やスラッシュメニューに表示されます。 | スキルが何をするか、いつ使うか、よくあるトリガーとなる語句を記述してください。 |
73+
| `metadata.allow-implicit-invocation` | 任意 | `false` に設定すると自動マッチングの対象から外れますが、手動での選択は引き続き可能です。 | 手動専用のスキルに使ってください。 |
74+
75+
例:
76+
77+
```yaml
78+
---
79+
name: db-migration
80+
description: Create and review database migrations for this project. Use when the user asks to add columns, change schema, write migrations, or validate rollback behavior.
81+
metadata:
82+
allow-implicit-invocation: false
83+
---
84+
```
85+
86+
> Deep Code CLIが現在解釈するのは上記のフィールドのみです。それ以外のフロントマターフィールドは、他クライアントとの互換性やドキュメント目的で役立つ場合がありますが、Deep Codeのツール権限を自動的に制限することはありません。
87+
88+
## 効果的な `description` の書き方
89+
90+
`description` は、スキルを見つけてもらうための最も重要なシグナルです。自動マッチングの際、Deep Codeがモデルに渡すのは各スキルの `name` と `description` だけなので、具体的に書くほど確実にマッチします。
91+
92+
推奨パターン:
93+
94+
```text
95+
<What this skill does>. Use when <task types, file types, domain, user phrases, or trigger terms>.
96+
```
97+
98+
良い例:
99+
100+
```yaml
101+
description: Extract tables from PDF files, fill PDF forms, and merge documents. Use when working with PDFs, forms, invoices, statements, or document extraction.
102+
```
103+
104+
```yaml
105+
description: Generate Lessweb routes, services, and Pydantic request models. Use when editing Lessweb projects, adding @Get/@Post endpoints, configuring IOC modules, or updating OpenAPI output.
106+
```
107+
108+
避けるべき例:
109+
110+
```yaml
111+
description: Helps with documents
112+
description: Useful project skill
113+
description: Tooling instructions
114+
```
115+
116+
チェックリスト:
117+
118+
- トピックだけでなく、具体的な機能を明記する
119+
- 期待される結果だけでなく、いつ使うのかを明記する
120+
- ユーザーが入力しそうな語句を含める
121+
- 関連するファイル形式、フレームワーク名、コマンド名、ドメイン名を含める
122+
- 無関係なタスクでも発動してしまうような、広すぎる表現を避ける
123+
124+
## スキル本文の構成
125+
126+
`SKILL.md` の本文は、一般の読者向けではなくエージェント向けに書いてください。直接的で、実行可能で、検証可能な内容に保ちます。
127+
128+
推奨構成:
129+
130+
```markdown
131+
# Skill Name
132+
133+
Briefly state what this skill is for.
134+
135+
## When to use
136+
137+
- Use when ...
138+
- Do not use when ...
139+
140+
## Workflow
141+
142+
1. Read ...
143+
2. Run ...
144+
3. Edit ...
145+
4. Verify ...
146+
147+
## Rules
148+
149+
- Preserve ...
150+
- Never ...
151+
- Ask the user when ...
152+
153+
## Examples
154+
155+
...
156+
```
157+
158+
執筆の原則:
159+
160+
- 「まずスキーマを読む」「編集後にテストを実行する」のように、命令形のステップで書く
161+
- 必ず守るべき制約は明示的なルールとして書く
162+
- ファイル削除、データ移行、リクエスト送信といった高リスクな操作には境界を定義する
163+
- 「設定ファイルがなければ、まずデフォルトのパスを探す」のように、よくある分岐を文書化する
164+
- 長いリファレンス資料は `SKILL.md` の外に移す
165+
166+
## 補助リソース
167+
168+
スキルには `SKILL.md` と同じ階層にファイルを含めることができます。
169+
170+
```text
171+
my-skill/
172+
├── SKILL.md
173+
├── references/
174+
│ └── api.md
175+
├── examples/
176+
│ └── request.json
177+
├── scripts/
178+
│ └── validate.py
179+
└── templates/
180+
└── report.md
181+
```
182+
183+
`SKILL.md` が長くなりすぎたり、一覧性が損なわれたりする資料には補助ファイルを使ってください。
184+
185+
- 長いドキュメント、仕様、APIノートは `references/` に置く
186+
- 入出力のサンプルは `examples/` に置く
187+
- 再利用可能なコマンドは `scripts/` に置く
188+
- ドキュメントやコードの雛形は `templates/` に置く
189+
- 各補助ファイルをいつ参照すべきかを `SKILL.md` で説明する
190+
191+
例:
192+
193+
```markdown
194+
## Workflow
195+
196+
1. Read `references/schema.md` before changing generated types.
197+
2. Use `templates/migration.sql` when creating a new migration.
198+
3. Run `python scripts/check_migration.py <file>` before reporting completion.
199+
```
200+
201+
## 呼び出し方法
202+
203+
Deep Code CLIはスキルの自動呼び出しと手動呼び出しの両方をサポートしています。
204+
205+
### 自動呼び出し
206+
207+
ユーザーのメッセージごとに、Deep Codeは利用可能なスキルの `name` と `description` フィールドを確認し、タスクに合致するスキルを選択します。マッチしたスキルは現在のセッションに読み込まれます。
208+
209+
自動呼び出しのルール:
210+
211+
- 一度読み込まれたスキルは、同じセッション内で再度読み込まれない
212+
- `metadata.allow-implicit-invocation: false` が設定されたスキルは自動では読み込まれない
213+
- マッチングでは現在の `AGENTS.md` の指示も考慮される
214+
- マッチするスキルがなければ、何も読み込まれない
215+
216+
### 手動呼び出し
217+
218+
入力ボックスに `/` と入力するとスキルとコマンドのメニューが開くので、そこからスキルを選択します。利用可能なスキルの一覧は `/skills` で確認できます。
219+
220+
よく使うコマンド:
221+
222+
| コマンド | 動作 |
223+
| ------- | -------- |
224+
| `/` | スキルとコマンドのメニューを開く |
225+
| `/skills` | 利用可能なスキルを一覧表示する |
226+
| `/<skill-name>` | メニューから該当するスキルを選択する |
227+
228+
## スキルの有効化と無効化
229+
230+
`settings.json` の `enabledSkills` を使うと、スキルを名前単位で有効化・無効化できます。
231+
232+
```json
233+
{
234+
"enabledSkills": {
235+
"code-review": true,
236+
"db-migration": false
237+
}
238+
}
239+
```
240+
241+
ルール:
242+
243+
- 記載されていないスキルはデフォルトで有効
244+
- スキルを `false` に設定すると、その解決名を持つスキャン済みスキルがすべて非表示になる
245+
- プロジェクト設定はスキルごとにユーザー設定を上書きする
246+
247+
詳細は [configuration_ja.md](configuration_ja.md) を参照してください。
248+
249+
## スキル vs. `AGENTS.md` vs. MCP
250+
251+
| 仕組み | 適している用途 | 適していない用途 |
252+
| --------- | -------- | ------------ |
253+
| `AGENTS.md` | 長期的なリポジトリルール、コーディングスタイル、テストコマンド、コラボレーション上の取り決め | 再利用可能な複雑なワークフローや、プロジェクト横断のツール指示 |
254+
| エージェントスキル | 再利用可能なワークフロー、ドメイン知識、テンプレート、スクリプト、リファレンスドキュメント | 単一タスク限りの一時的な要件 |
255+
| MCP | 外部システム、ライブデータ、ブラウザ操作、データベース、GitHubなどのツール呼び出し | 純粋なテキストベースのワークフロー指示 |
256+
257+
よくあるパターン:
258+
259+
- リポジトリルールは `AGENTS.md` に置く
260+
- 再利用可能なワークフローはスキルに置く
261+
- 外部への操作はMCPツールに任せる
262+
263+
## 例: プロジェクトリリーススキル
264+
265+
```markdown
266+
---
267+
name: release-check
268+
description: Prepare and verify a project release. Use when the user asks to release, publish, bump version, update changelog, or run pre-release checks.
269+
---
270+
271+
# Release Check
272+
273+
Use this skill to prepare a safe release for this repository.
274+
275+
## Workflow
276+
277+
1. Read `package.json` and the existing changelog.
278+
2. Inspect commits or diffs since the previous release tag.
279+
3. Update version and changelog only when the user explicitly asks.
280+
4. Run the project test and build commands.
281+
5. Report the version, changed files, verification results, and remaining risks.
282+
283+
## Rules
284+
285+
- Do not publish packages unless the user explicitly asks.
286+
- Do not create or push git tags without explicit approval.
287+
- Preserve existing changelog style.
288+
```
289+
290+
## トラブルシューティング
291+
292+
### スキルが `/skills` に表示されない
293+
294+
確認事項:
295+
296+
1. ディレクトリがDeep Codeのスキャン対象の場所のいずれかにあるか
297+
2. ファイル名が `SKILL.md` になっているか
298+
3. `SKILL.md` が `.deepcode/skills/my-skill/SKILL.md` のように専用のスキルディレクトリ内にあるか
299+
4. `enabledSkills` でそのスキルが `false` に設定されていないか
300+
5. 同名のより高優先度のスキルに隠されていないか
301+
302+
### 自動呼び出しが安定しない
303+
304+
確認事項:
305+
306+
1. `description` に明確なユースケースとトリガーとなる語句が含まれているか
307+
2. スキルが広すぎて、モデルが適用範囲を推測できなくなっていないか
308+
3. `metadata.allow-implicit-invocation` が `false` に設定されていないか
309+
4. ユーザーのリクエストが、関連するドメインやファイル形式を十分明確に言及しているか
310+
311+
### スキルが長すぎる
312+
313+
推奨事項:
314+
315+
1. 中核となるワークフローとルールは `SKILL.md` に残す
316+
2. 長いドキュメントは `references/` に移す
317+
3. 繰り返し使うコマンドは `scripts/` に移す
318+
4. 各補助ファイルをエージェントがいつ読むべきかを説明する
319+
320+
## 参考資料
321+
322+
- [Agent Skills Specification](https://agentskills.io/specification)

0 commit comments

Comments
 (0)