sherpy-cli

Sherpy CLI

Sherpy の YAML ドキュメントをスキーマに照らして検証し、書式を整えた Markdown に変換します。実装ワークフローで使用する前に、計画ドキュメントが構造要件を満たしていることを確認できます。

使用する場面

次の作業が必要なときに、このスキルを呼び出します。

• Sherpy の YAML ドキュメント（ビジネス要件、技術要件、マイルストーン、タスク、タイムライン、QA 計画、ギャップ分析）を検証する
• 有効な YAML を読みやすい Markdown ドキュメントに変換する
• 計画ワークフローで使用する前に、ドキュメントの構造を確認する
• 計画成果物からドキュメントを生成する
• 計画ドキュメントの検証エラーや警告を確認する

対応するドキュメントの種類

種類	ファイルパターン	目的
business-requirements	business-requirements.yaml	ペルソナとユースケースを含むビジネス要件
technical-requirements	technical-requirements.yaml	技術仕様とアーキテクチャ上の決定
milestones	milestones.yaml	依存関係を含むプロジェクトのマイルストーン
milestone-tasks	milestone-m*.tasks.yaml	詳細なタスク分解（各 30～150 分）
timeline	timeline.yaml	逆算日程を含む納期タイムライン
qa-test-plan	qa-test-plan.yaml	QA テストスイートとテストケース
gap-analysis	gap-analysis-worksheet.yaml	ギャップ分析ワークシート

使い方

基本的な検証

# Validate a document
sherpy validate -t business-requirements -f docs/business-requirements.yaml

# Validate with strict mode (warnings become errors)
sherpy validate -t business-requirements -f docs/business-requirements.yaml --strict

Markdown に変換

# Convert to stdout
sherpy to-markdown -t business-requirements -f docs/business-requirements.yaml

# Convert to file
sherpy to-markdown -t business-requirements -f docs/business-requirements.yaml -o output.md

ドキュメントの種類を一覧表示

sherpy types

スキルのプロンプト指示を読み込む

AI エージェント向けのスキルプロンプト指示を出力します（CLI 専用機能）。

# List available prompts
sherpy prompt --list

# Output specific skill instructions (for AI agents)
sherpy prompt -t business-requirements-interview
sherpy prompt -t implementation-planner
sherpy prompt -t qa-test-plan

sherpy prompt コマンドは、YAML フロントマターを除いた埋め込み済みのスキル指示を出力します。個々のスキルファイルをインストールする代わりに、トークン効率のよい方法として利用できます。コンテンツはビルド時にバイナリへ埋め込まれます。

利用可能なプロンプト：

• gap-analysis-worksheet、business-requirements-interview、technical-requirements-interview
• style-anchors-collection、implementation-planner、implementation-plan-review
• definition-of-done、architecture-decision-record、delivery-timeline
• qa-test-plan、developer-summary、executive-summary

CLI を介した計画ワークフローのオーケストレーションについては、sherpy-cli-planner スキルも参照してください。

検証機能

Sherpy CLI は包括的な検証を実行します。

スキーマ検証

• ✅ 必須フィールドの有無と型の正しさ
• ✅ フィールドの長さ制限（最小／最大文字数）
• ✅ 列挙値（優先度、種類、戦略）
• ✅ 日付形式（YYYY-MM-DD）

フィールド間の検証

• ✅ 連番の ID（FR-1、FR-2、FR-3）
• ✅ ID 参照（ユースケースのアクターがペルソナに存在すること）
• ✅ 依存関係の解決（タスクが有効なタスク ID を参照していること）
• ✅ 循環依存の検出

ビジネスルール

• ✅ マイルストーン数とタイムラインの項目数の一致
• ✅ タスク期間が上限内であること
• ✅ 逆算日付の計算
• ✅ QA カバレッジ率
• ✅ 割り当て率の合計が 100% であること

出力モード

• デフォルト：エラーを表示し、警告は情報として表示します
• 厳格：警告をエラーに昇格させます（CI/CD で使用）
• 詳細：コンテキストを含む詳細なエラーメッセージを表示します

セキュリティ機能

Sherpy CLI には、複数のセキュリティ保護機能が含まれています。

パストラバーサル対策

• ../../etc/passwd 攻撃を防ぐため、ファイルパスを検証します
• MaxDepth を適用します
• シンボリックリンクを検出してブロックします

ファイルサイズ制限

• ファイルサイズの上限は 10MB です
• 早期に拒否することで、メモリ枯渇を防ぎます
• DoS 攻撃から保護します

セキュアな権限

• 出力ファイルは 0600（ユーザーのみ読み書き可能）で作成します
• グループおよびその他のユーザーからアクセスできません
• 機密性の高い計画ドキュメントを保護します

インジェクション防止

• Markdown の特殊文字をエスケープします
• HTML エンティティをエンコードします
• 生成されるドキュメントでの XSS を防ぎます

ReDoS 対策

• MaxIDLength は 100 文字です
• 正規表現の評価前に長さを検証します
• CPU 枯渇攻撃を防ぎます

ワークフローとの統合

Sherpy 計画ワークフロー

Sherpy の計画スキルを使用する場合は、生成後にドキュメントを検証します。

# After business-requirements-interview
sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict

# After technical-requirements-interview
sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict

# After implementation-planner
sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict
sherpy validate -t milestone-tasks -f docs/implementation/tasks/milestone-m0.tasks.yaml --strict

# After delivery-timeline
sherpy validate -t timeline -f docs/delivery/timeline.yaml --strict

# After qa-test-plan
sherpy validate -t qa-test-plan -f docs/delivery/qa-test-plan.yaml --strict

コミット前の検証

エラーを早期に検出するため、コミット前フックに検証を追加します。

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating Sherpy documents..."

# Find all YAML files in docs/
for file in docs/**/*.yaml; do
  if [ -f "$file" ]; then
    # Determine type from path
    case "$file" in
      *business-requirements.yaml)
        sherpy validate -t business-requirements -f "$file" --strict || exit 1
        ;;
      *technical-requirements.yaml)
        sherpy validate -t technical-requirements -f "$file" --strict || exit 1
        ;;
      *milestones.yaml)
        sherpy validate -t milestones -f "$file" --strict || exit 1
        ;;
      *tasks.yaml)
        sherpy validate -t milestone-tasks -f "$file" --strict || exit 1
        ;;
      *timeline.yaml)
        sherpy validate -t timeline -f "$file" --strict || exit 1
        ;;
      *qa-test-plan.yaml)
        sherpy validate -t qa-test-plan -f "$file" --strict || exit 1
        ;;
      *gap-analysis*.yaml)
        sherpy validate -t gap-analysis -f "$file" --strict || exit 1
        ;;
    esac
  fi
done

echo "✓ All documents validated successfully"

CI/CD との統合

GitHub Actions

name: Validate Sherpy Documents

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Sherpy CLI
        run: go install github.com/validkeys/sherpy@latest
      
      - name: Validate Planning Documents
        run: |
          sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
          sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict
          sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict

GitLab CI

validate-docs:
  stage: test
  image: golang:1.26
  script:
    - go install github.com/validkeys/sherpy@latest
    - sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
    - sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict

ドキュメントの生成

すべての計画成果物から Markdown ドキュメントを生成します。

#!/bin/bash
# generate-docs.sh

set -e

echo "Generating documentation from YAML sources..."

# Validate all documents first
echo "1. Validating documents..."
sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict
sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict

# Convert to markdown
echo "2. Converting to markdown..."
mkdir -p docs/generated

sherpy to-markdown -t business-requirements \
  -f docs/requirements/business-requirements.yaml \
  -o docs/generated/business-requirements.md

sherpy to-markdown -t technical-requirements \
  -f docs/requirements/technical-requirements.yaml \
  -o docs/generated/technical-requirements.md

sherpy to-markdown -t milestones \
  -f docs/implementation/milestones.yaml \
  -o docs/generated/milestones.md

echo "✓ Documentation generated in docs/generated/"

よくある検証エラー

連番 ID のエラー

# ❌ Wrong: Non-sequential IDs
functional_requirements:
  - id: FR-1
  - id: FR-3  # Error: expected FR-2

# ✅ Correct: Sequential IDs
functional_requirements:
  - id: FR-1
  - id: FR-2

循環依存のエラー

# ❌ Wrong: Circular dependency
milestones:
  - id: m0
    dependencies: [m1]
  - id: m1
    dependencies: [m0]  # Error: circular dependency

# ✅ Correct: Linear dependencies
milestones:
  - id: m0
    dependencies: []
  - id: m1
    dependencies: [m0]

無効な参照のエラー

# ❌ Wrong: Reference to non-existent persona
use_cases:
  - actor: "AdminUser"  # Error: AdminUser not in personas

# ✅ Correct: Reference existing persona
personas:
  - name: "AdminUser"
    role: "Administrator"

use_cases:
  - actor: "AdminUser"  # OK

タスク期間のエラー

# ❌ Wrong: Task exceeds max duration
tasks:
  - id: m0-001
    estimate_minutes: 200  # Error: exceeds max 150 minutes

# ✅ Correct: Task within limits
tasks:
  - id: m0-001
    estimate_minutes: 120  # OK

ベストプラクティス

1. 変換前に検証する

ドキュメントは必ず Markdown に変換する前に検証します。

sherpy validate -t business-requirements -f input.yaml --strict && \
  sherpy to-markdown -t business-requirements -f input.yaml -o output.md

2. CI/CD で厳格モードを使用する

自動化されたワークフローで厳格モードを有効にし、すべての問題を検出します。

sherpy validate -t business-requirements -f docs/file.yaml --strict

3. 計画の各ステップ後に検証する

Sherpy の計画スキルを実行した後は、出力を検証します。

# After /business-requirements-interview
sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict

# After /implementation-planner
sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict
for file in docs/implementation/tasks/*.yaml; do
  sherpy validate -t milestone-tasks -f "$file" --strict
done

4. ファイルのアクセス許可を確認する

出力ファイルに安全なアクセス許可が設定されていることを確認します。

sherpy to-markdown -t business-requirements -f input.yaml -o output.md
ls -l output.md  # Should show -rw------- (600)

5. スクリプトでは絶対パスを使用する

自動化でパスの混乱を避けます。

DOCS_DIR="$(cd "$(dirname "$0")" && pwd)/docs"
sherpy validate -t business-requirements -f "$DOCS_DIR/requirements/business-requirements.yaml"

6. 変更したファイルをまとめて検証する

変更したドキュメントのみを検証します。

git diff --name-only HEAD | grep '\.yaml$' | while read file; do
  type=$(basename "$file" .yaml)
  sherpy validate -t "$type" -f "$file" --strict
done

終了コード

• 0 - 成功（検証に合格し、変換に成功）
• 1 - 検証失敗またはコマンドエラー
• 2 - ファイルが見つからない、または読み取りエラー

インストール

ソースから

git clone https://github.com/validkeys/sherpy.git
cd sherpy
make build
sudo make install

Go を使用

go install github.com/validkeys/sherpy@latest

インストールの確認

sherpy types

トラブルシューティング

エラー：「file not found」

ファイルが存在することを確認し、絶対パスを使用します。

ls -la docs/business-requirements.yaml
sherpy validate -t business-requirements -f "$(pwd)/docs/business-requirements.yaml"

エラー：「unknown document type」

有効なタイプを一覧表示し、スペルを確認します。

sherpy types
# Use exact type name: business-requirements (not business_requirements)

エラー：「failed to parse YAML」

YAML の構文を確認します。

yamllint docs/business-requirements.yaml
# Common issues: mixed tabs/spaces, incorrect indentation, unquoted special chars

エラー：「path traversal blocked」

親ディレクトリへの参照は使用しないでください。

# ❌ Blocked
sherpy validate -t business-requirements -f ../../etc/passwd

# ✅ Use absolute paths or paths within working directory
sherpy validate -t business-requirements -f /absolute/path/to/file.yaml
sherpy validate -t business-requirements -f ./docs/file.yaml

エラー：「file exceeds maximum size」

ファイルサイズは 10MB 未満である必要があります。

# Check file size
stat -f%z docs/file.yaml  # macOS
stat -c%s docs/file.yaml  # Linux

# Maximum: 10485760 bytes (10MB)

関連スキル

• business-requirements-interview - business-requirements.yaml を生成
• technical-requirements-interview - technical-requirements.yaml を生成
• implementation-planner - milestones.yaml とタスクファイルを生成
• delivery-timeline - timeline.yaml を生成
• qa-test-plan - qa-test-plan.yaml を生成
• gap-analysis-worksheet - gap-analysis-worksheet.yaml を生成
• sherpy-flow - 検証を含む計画ワークフロー全体を統括

ドキュメント

• GitHub：https://github.com/validkeys/sherpy
• README：README.md
• 使用ガイド：USAGE.md
• セキュリティ：SECURITY.md

例

ディレクトリ内のすべてのドキュメントを検証する

#!/bin/bash
# validate-all.sh

DOCS_DIR="docs"
ERRORS=0

for file in "$DOCS_DIR"/**/*.yaml; do
  if [ -f "$file" ]; then
    echo "Validating $file..."
    
    # Determine type from filename/path
    case "$file" in
      *business-requirements.yaml) type="business-requirements" ;;
      *technical-requirements.yaml) type="technical-requirements" ;;
      *milestones.yaml) type="milestones" ;;
      *tasks.yaml) type="milestone-tasks" ;;
      *timeline.yaml) type="timeline" ;;
      *qa-test-plan.yaml) type="qa-test-plan" ;;
      *gap-analysis*.yaml) type="gap-analysis" ;;
      *) continue ;;
    esac
    
    if ! sherpy validate -t "$type" -f "$file" --strict; then
      ERRORS=$((ERRORS + 1))
    fi
  fi
done

if [ $ERRORS -eq 0 ]; then
  echo "✓ All documents validated successfully"
  exit 0
else
  echo "✗ Validation failed for $ERRORS document(s)"
  exit 1
fi

すべてのドキュメントを Markdown に変換する

#!/bin/bash
# convert-all.sh

mkdir -p docs/generated

TYPES=(
  "business-requirements:docs/requirements/business-requirements.yaml"
  "technical-requirements:docs/requirements/technical-requirements.yaml"
  "milestones:docs/implementation/milestones.yaml"
  "timeline:docs/delivery/timeline.yaml"
  "qa-test-plan:docs/delivery/qa-test-plan.yaml"
)

for entry in "${TYPES[@]}"; do
  IFS=':' read -r type file <<< "$entry"
  
  if [ -f "$file" ]; then
    output="docs/generated/$(basename "$file" .yaml).md"
    echo "Converting $file -> $output"
    
    if sherpy validate -t "$type" -f "$file" --strict; then
      sherpy to-markdown -t "$type" -f "$file" -o "$output"
      echo "✓ Converted $type"
    else
      echo "✗ Validation failed for $file, skipping conversion"
    fi
  fi
done

echo "✓ Conversion complete - see docs/generated/"

Makefile との統合

.PHONY: validate validate-strict convert-all docs

# Validate all Sherpy documents
validate:
	@echo "Validating Sherpy documents..."
	@sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml
	@sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml
	@sherpy validate -t milestones -f docs/implementation/milestones.yaml
	@echo "✓ Validation complete"

# Validate with strict mode (for CI/CD)
validate-strict:
	@echo "Validating Sherpy documents (strict mode)..."
	@sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
	@sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict
	@sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict
	@sherpy validate -t timeline -f docs/delivery/timeline.yaml --strict
	@sherpy validate -t qa-test-plan -f docs/delivery/qa-test-plan.yaml --strict
	@echo "✓ Strict validation passed"

# Convert all documents to markdown
convert-all:
	@mkdir -p docs/generated
	@echo "Converting Sherpy documents to markdown..."
	@sherpy to-markdown -t business-requirements -f docs/requirements/business-requirements.yaml -o docs/generated/business-requirements.md
	@sherpy to-markdown -t technical-requirements -f docs/requirements/technical-requirements.yaml -o docs/generated/technical-requirements.md
	@sherpy to-markdown -t milestones -f docs/implementation/milestones.yaml -o docs/generated/milestones.md
	@sherpy to-markdown -t timeline -f docs/delivery/timeline.yaml -o docs/generated/timeline.md
	@sherpy to-markdown -t qa-test-plan -f docs/delivery/qa-test-plan.yaml -o docs/generated/qa-test-plan.md
	@echo "✓ Conversion complete"

# Generate all documentation
docs: validate-strict convert-all
	@echo "✓ Documentation generated in docs/generated/"

まとめ

Sherpy CLI は、Sherpy の計画ドキュメントの検証および変換エンジンです。次の用途に使用します。

1. YAML ドキュメントを使用前にスキーマに照らして検証する
2. 有効な YAML を読みやすい Markdown ドキュメントに変換する
3. CI/CD パイプラインに検証を統合する
4. 厳格モードでドキュメントの品質基準を徹底する
5. 計画成果物からドキュメントを生成する

構造上のエラーを早期に検出するため、計画スキルでドキュメントを生成した後は必ず検証してください。本番環境で使用できる計画ドキュメントを確実に作成するには、自動化されたワークフローで厳格モードを使用してください。