Skip to content
Skills Library
Programming · Planning

technical-spec

/technical-spec

環境変数、アーキテクチャ設計、ビルド・テストコマンドを定義。環境設定、アーキテクチャ設計時に使用。

Licence
MIT
Last repository change
23.10.2026

Assessment and security

86/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

環境変数、アーキテクチャ設計、ビルド・テストコマンドを定義。環境設定、アーキテクチャ設計時に使用。

Original author description

環境変数、アーキテクチャ設計、ビルド・テストコマンドを定義。環境設定、アーキテクチャ設計時に使用。

How it works

  1. 前提条件の検出
  2. 技術スタックの基本方針
  3. 環境変数管理とセキュリティ
  4. アーキテクチャ設計
  5. データフロー統一原則
  6. ビルドとテスト
Original SKILL.md headings · 95 lines, 169 words
SKILL.md preview
---
name: technical-spec
description: 環境変数、アーキテクチャ設計、ビルド・テストコマンドを定義。環境設定、アーキテクチャ設計時に使用。
---

# 技術設計ルール

## 前提条件の検出

技術やコマンドに固有のルールを適用する前に、マニフェスト、ロックファイル、ビルド・テスト設定、CI定義、代表的なソースファイルを確認する。ツール、スクリプト、パスエイリアス、ランタイムは、リポジトリ内の根拠に明記されている場合にのみ確認済みとして扱う。周辺のパターンから導いた結論には推測であることを明記する。不足している判断によってアーキテクチャ、互換性、セキュリティ、検証方法が変わる場合は作業を止め、必要な設定またはユーザー判断を具体的に示す。

## 技術スタックの基本方針
リポジトリ設定からTypeScriptアプリケーションであることを確認できる場合に、このルールを適用する。現行要件と合意済みの制約を、モジュールの責務、依存方向、データフロー、検証境界へ明示的に対応付けてアーキテクチャを選択する。

## 環境変数管理とセキュリティ

### 環境変数管理
- 環境変数と、その型安全性を担保するビルド時の検証機構を一元管理する
- 環境変数は1つの型付き設定境界で読み取り、アプリケーションコードでは検証済みの設定値を使用する
- 要件で未設定時の有効な振る舞いが定義されている場合にのみデフォルト値を設ける。それ以外は、変数名と期待する形式を示して設定検証を失敗させる

### セキュリティ
- ローカルの`.env`ファイルはバージョン管理の対象外とし、必要な変数名はシークレットを含まないサンプルファイルで示す
- APIキーやシークレットは、設定済みのシークレットストアまたはランタイム環境との境界から読み込む
- 現在の信頼境界で許可されたフィールドだけをログおよびレスポンスに含める。認証情報、トークン、個人データ、内部診断情報は、信頼されていない相手に返す前に除去する

## アーキテクチャ設計

### アーキテクチャ設計の原則
以下の観測可能な判断に基づいてアーキテクチャを選択する:

- **責務**: 各モジュールや層について、自身が担う振る舞いと委譲する振る舞いを明記する
- **依存方向**: importとランタイム呼び出しは、設定または代表的な実装から確認したプロジェクトの境界ルールに従う
- **状態・データの所有者**: 永続化される値または可変値ごとに、唯一の正規の所有者を定める
- **検証境界**: 公開契約ごとに、それを観測できるUnit、Integration、E2Eいずれかのチェックを設ける

## データフロー統一原則

#### 基本原則
1. **単一データソース**: 同じ情報は1箇所にのみ保存する
2. **構造化データ優先**: JSON文字列ではなくパース済みオブジェクトを使用
3. **責務の分離**: 各層が所有するデータまたは振る舞いと、他の層が利用するための境界を明記する

#### データフローのベストプラクティス
- **入力時点での検証**: データは入力層で検証し、型安全な形で内部に渡す
- **変換の一元化**: データ変換ロジックは専用のユーティリティに集約
- **ログの構造化**: データフローの各段階で構造化ログを出力

## ビルドとテスト
`packageManager`フィールド、ロックファイル、確立済みのCIコマンドの順にパッケージマネージャーを判定する。選択したマニフェストに存在するスクリプトだけを実行する。

### ビルドコマンド
- `build` - TypeScriptビルド
- `type-check` - 型チェック(emit なし)

### テストコマンド
- `test` - テスト実行

### 品質保証メカニズムの認識

品質チェック実行前に、変更対象領域にどのような品質メカニズムが存在するかを特定する:
- 一次検出: 変更対象のファイル種別、プロジェクトマニフェスト、設定から適用可能な品質ツールを特定
  - 影響パスをカバーするCIパイプライン定義を確認
  - ドメイン固有のlinterやバリデータ設定(スキーマバリデータ、API specバリデータ、設定ファイルリンター等)を確認
  - プロジェクト設定におけるドメイン固有の制約(命名規約、文字数制限、フォーマット要件)を確認
- タスクファイルが Operation Verification Methods を提供している場合、それらをタスク固有のチェックとして実行する
- 検出したドメイン固有チェックを以下の標準品質フェーズに併せて実行

### 品質チェック要件

品質チェックは実装完了時に必須:

**Phase 1-3: コード品質チェック**
- package.jsonから以下に該当するスクリプトを自動検出して実行:
  - lint + format チェック
  - 未使用エクスポートの検出
  - 循環依存の検出
  - TypeScriptビルド

**フェーズ移行条件**: 適用対象となる静的チェックとドメイン固有チェックがすべて正常終了していること。必須スクリプトが存在しない場合はマニフェストまたは設定のパスとともに報告し、残りのチェックは引き続き実行する。そのチェックがないことで必要な証明が得られなくなるかどうかは、quality-fixerの結果で判断する。

**Phase 4: テスト**
- `test` - テスト実行

**フェーズ移行条件**: 適用対象として設定されているテストスイートがすべて成功していること。環境依存のテストスイートを実行できない場合は、ブロック要因となる前提条件を具体的に記録する。

**Phase 5: コード品質再検証**
- `check:code` - コード品質の再検証(Phase 4でのテスト修正による副作用を解消)

**完了条件**: テストに伴う修正後も静的チェックとドメイン固有チェックが成功し、ビルドが成功していること。必須テストはすべて成功しているか、実行を妨げる要因が明示されていること。

### 補助コマンド
- `check:all` - 全体統合チェック(check:code + test)※手動一括確認用
- `format` - フォーマット修正
- `lint:fix` - Lint修正

### トラブルシューティング
- **依存関係エラー**: まず、失敗した依存解決処理の出力、選択したパッケージマネージャー、マニフェスト、ロックファイルの状態を記録する。ロックファイルと生成物を維持できる、リポジトリで確立済みのクリーンインストールコマンドだけを使用する。依存関係の状態を削除または再生成する操作には事前承認を得る

Versions

RepositoryScoreLicence
This page · shinpr/ai-coding-project-boilerplate86MIT
majiayu000/spellbook100MIT
shinpr/ai-coding-project-boilerplate100MIT
zph/dotfiles100MIT
SkillMedev/skills90MIT
shinpr/ai-coding-project-boilerplate82MIT

Database snapshot: 13.11.2026 · package version f803d6755332 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100frontend-technical-spec
    リポジトリの根拠に基づき、Reactの環境、コンポーネントアーキテクチャ、状態・データフロー、ビルド検証、フロントエンドの非機能基準を定義。Reactフロントエンド、そのビルド、ランタイム境界の設定・設計時に使用。
  • 91architecture-spec
    Generates technical architecture specification from PRD. Covers architecture pattern, tech stack, data models, and app structure. Use when creating ARCHITECTURE.md or designing system architecture.
  • 100kiro-spec-design
    Generate comprehensive technical design translating requirements (WHAT) into architecture (HOW) with discovery process. Use when creating architecture from requirements.
  • 96frontend-technical-spec
    根据仓库依据定义 React 环境、组件架构、状态/数据流、构建验证以及前端非功能性标准。用于配置或设计 React 前端及其构建、运行时边界时使用。
  • 100unity-build
    ビルドワークフロー。検証 → 設定確認 → ビルド実行 → エラー対応。 Use for: "ビルド", "ビルド実行", "プラットフォーム設定", "ビルドエラー
  • 100dev-verify
    This skill should be used when the user asks to "dev-verify", "実装の検証", "完了チェック", "verify implementation", "全テスト実行", "run all tests", "dev-verify auth". Plan単位で全タスクの完了状態とテスト・ビルド・Lintの整合性を検証し、レポートを出力する。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.