⛳

spec-kitの成果物を確実に日本語で作成する

に公開
テーマ「AI駆動開発でやったこと」
zennfes2025ai
Spec Kit
tech

はじめに

GitHubから仕様駆動開発(SDD: Spec-Driven Development)を支援するためのツールであるSpec Kitがリリースされました。

リポジトリはこちら。
https://github.com/github/spec-kit

Spec Kitとは

Spec KitはClaude CodeやGitHub CopilotなどのAIエージェントを使用して、要件定義、設計、タスク化を行うコマンドと、そのコマンドの中で使用するテンプレートを生成します。
これにより、ユーザーが使用している任意のAIエージェントを使用してSDDを行うことができます。

2025/09/24 時点では以下のAIエージェントがサポートされています。

  • Claude Code
  • GitHub Copilot
  • Gemini CLI
  • Cursor
  • Qwen Code
  • opencode
  • Windsurf
  • Kilo Code
  • Auggie CLI
  • Roo Code
  • Codex CLI(Codex CLIがスラッシュコマンドの引数に対応していない)

Spec Kitの具体的な使い方などは以下の記事が詳しいので、割愛します。
https://zenn.dev/beagle/articles/7976e6ac40c762

Spec Kitの成果物を日本語で作成したい

私はClaude CodeとGitHub CopilotでSpec Kitを試してみました。
init コマンドで生成されるコマンドやテンプレートは英語なので、そのままコマンド(/specifyや/plan、/tasks)を実行すると、作成される成果物は英語になります。
私は成果物を日本語で作成してほしいため、以下を試してみました。

  • コマンドのプロンプト部分に、「UTF-8の日本語で書いて」(英語で)のような文言を追加する
  • プロンプトやテンプレートすべてを日本語に変換する

結果として、どちらのパターンでも成果物が文字化けしてしまいました。
一応、成果物作成後に「文字化けを修正して」のような指示を追加で行えば、文字化けは解消されるのですが、さすがに毎回そのような指示を出すのは面倒です。

最終的に、以下の2点をコマンドのプロンプトに追加することで、成果物を日本語で作成することができるようになりました。

  • 成果物作成後に、文字化けしているかを検証する
  • 成果物が文字化けしている場合は、修正する

私は以下のように各タスクのプロンプトに追記しました。

specify
Given the feature description provided as an argument, do this:

1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
2. Load `.specify/templates/spec-template.md` to understand required sections.
3. Write the specification to SPEC_FILE in Japanese with UTF-8 encoding using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+ 4. Verify that SPEC_FILE contains properly encoded Japanese text without character corruption. If corrupted characters are detected, rewrite the file.
5. Report completion with branch name, spec file path, and readiness for the next phase.
plan
Given the implementation details provided as an argument, do this:

1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
2. Read and analyze the feature specification to understand:
   - The feature requirements and user stories
   - Functional and non-functional requirements
   - Success criteria and acceptance criteria
   - Any technical constraints or dependencies mentioned

3. Read the constitution at `.specify/memory/constitution.md` to understand constitutional requirements.

4. Execute the implementation plan template:
   - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
   - Set Input path to FEATURE_SPEC
   - Run the Execution Flow (main) function steps 1-9
   - The template is self-contained and executable
   - Follow error handling and gate checks as specified
   - Let the template guide artifact generation in $SPECS_DIR:
     * Phase 0 generates research.md in Japanese with UTF-8 encoding
     * Phase 1 generates data-model.md, contracts/, quickstart.md in Japanese with UTF-8 encoding
     * Phase 2 generates tasks.md in Japanese with UTF-8 encoding
   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
   - Update Progress Tracking as you complete each phase
5. Verify execution completed:
   - Check Progress Tracking shows all phases complete
   - Ensure all required artifacts were generated
+   - Verify all required artifacts contain properly encoded Japanese text without character corruption. If corrupted characters are detected, rewrite the file.
   - Confirm no ERROR states in execution

6. Report results with branch name, file paths, and generated artifacts.
tasks
Given the context provided as an argument, do this:

1. Run `.specify/scripts/bash/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
2. Load and analyze available design documents:
   - Always read plan.md for tech stack and libraries
   - IF EXISTS: Read data-model.md for entities
   - IF EXISTS: Read contracts/ for API endpoints
   - IF EXISTS: Read research.md for technical decisions
   - IF EXISTS: Read quickstart.md for test scenarios

   Note: Not all projects have all documents. For example:
   - CLI tools might not have contracts/
   - Simple libraries might not need data-model.md
   - Generate tasks based on what's available

3. Generate tasks following the template:
   - Use `.specify/templates/tasks-template.md` as the base
   - Replace example tasks with actual tasks based on:
     * **Setup tasks**: Project init, dependencies, linting
     * **Test tasks [P]**: One per contract, one per integration scenario
     * **Core tasks**: One per entity, service, CLI command, endpoint
     * **Integration tasks**: DB connections, middleware, logging
     * **Polish tasks [P]**: Unit tests, performance, docs

4. Task generation rules:
   - Each contract file → contract test task marked [P]
   - Each entity in data-model → model creation task marked [P]
   - Each endpoint → implementation task (not parallel if shared files)
   - Each user story → integration test marked [P]
   - Different files = can be parallel [P]
   - Same file = sequential (no [P])
   - Use Japanese with UTF-8 encoding

5. Order tasks by dependencies:
   - Setup before everything
   - Tests before implementation (TDD)
   - Models before services
   - Services before endpoints
   - Core before integration
   - Everything before polish

6. Include parallel execution examples:
   - Group [P] tasks that can run together
   - Show actual Task agent commands

7. Create FEATURE_DIR/tasks.md in Japanese with UTF-8 encoding with:
   - Correct feature name from implementation plan
   - Numbered tasks (T001, T002, etc.)
   - Clear file paths for each task
   - Dependency notes
   - Parallel execution guidance

+ 8. Verify tasks.md contains properly encoded Japanese text without character corruption. If corrupted characters are detected, rewrite the file.

Discussion