# Treasure AI Studio: Project機能セットアップガイド

Koshi Nakamura
## Project機能とは

AIプロダクトを使っていて、同じプロンプトなのに結果が異なるということや、意図した結果が得られないということがあると思います。
これは、多くの場合AIはなにかを実行するまではその実行内容に関するコンテクストを十分に持っていないことと、ふるまいが確率的であるということに起因します。

Treasure AI Studioでは様々なスキルが用意されており、すぐにご利用いただけますが、あなたのビジネスの文脈や分析したいデータの情報、分析時のルールをクエリの実行や何かのアウトプットを作らせる前に参照できる状態にしておくことで、より一貫した品質と、期待する出力を得ることができるようになります。

Treasure AI StudioのProject機能は、チャットセッション間で**共通の前提知識を維持**する仕組みです。データスキーマ、ビジネスルール、過去の設計判断などをプロジェクトに保存することで、毎回同じ説明を繰り返す必要がなくなります。

このブログでは、Projectの使い方の例を紹介します。あなたのビジネスやデータの状況に応じて内容は適宜書き換えてご利用ください。

## フォルダ構造の例

例えば以下のような構成はエージェントにとって読みやすい構造です：


```
/home/agent/projects/<your-project-name>/
│
├── CLAUDE.md                     # プロジェクト設定ファイル（@importで他ファイルを参照）
│
├── skills/
│   ├── data-schema.md            # テーブル・カラム定義
│   └── business-rules.md         # KPI定義・命名規則・業務ルール
│
└── memory/
    ├── MEMORY.md                 # インデックスファイル
    └── decisions.md              # 設計判断の記録
```

### 各ファイルの役割

| ファイル | 用途 |
|  --- | --- |
| **CLAUDE.md** | プロジェクト全体の設定。skills/とmemory/を`@import`で読み込む |
| **skills/data-schema.md** | 利用可能なテーブル、カラム、データ型の定義 |
| **skills/business-rules.md** | KPIの計算式、許可された軸・指標、命名規則 |
| **memory/MEMORY.md** | 記憶のインデックス（自動生成） |
| **memory/decisions.md** | 過去の設計判断や注意事項を記録 |


## セットアップ手順

### Step 1: Projectを作成

1. Treasure AI Studioにログイン
2. 左サイドバーから **"Projects"** をクリック
3. **"New Project"** をクリック
4. プロジェクト名を入力（例: `customer-journey-analysis`）


![Project作成画面](/assets/01-project-creation.718098d1e86dc3c92dc3ddf3d8e4716d322c8f1bf2007416bd78bf8f9fcbc004.94e46156.png)

### Step 2: フォルダ構造を作成

新規Projectでは `/home/agent/projects/<your-project-name>/` が自動的に作成されます。ただし、`skills/` と `memory/` のサブフォルダは自動では作成されないため、別途作成が必要です。

Project内のチャットでTAISに以下のように指示するだけで作成できます：

> 「このプロジェクト内に `skills/` と `memory/` フォルダを作成してください。」


または、以下のコマンドを直接実行することで、確実かつ素早く作成することもできます：


```bash
mkdir -p /home/agent/projects/<your-project-name>/skills
mkdir -p /home/agent/projects/<your-project-name>/memory
```

![Project内のファイルツリー表示](/assets/02-file-tree.8e60c11488aba292cda236718d8a756fe2d4c7c6f339fb2350331bb74b9602f9.94e46156.png)

### Step 3: skills/data-schema.md を作成

データスキーマを明確に定義することで、AIが正しいテーブル・カラムを参照できます。


```markdown
# Data Schema

## テーブル一覧

### members（会員テーブル）
| カラム | 型 | 説明 |
|--------|-----|------|
| member_id | STRING | 会員ID（PK） |
| age_group | STRING | 年代（'20s', '30s', '40s', '50s+') |
| member_stage | STRING | 会員ステージ（'bronze', 'silver', 'gold', 'platinum') |
| registered_at | TIMESTAMP | 登録日時 |

### card_transactions（カード利用履歴）
| カラム | 型 | 説明 |
|--------|-----|------|
| transaction_id | STRING | 取引ID（PK） |
| member_id | STRING | 会員ID（FK: members） |
| amount | DECIMAL | 利用金額 |
| transaction_date | DATE | 利用日 |
| category | STRING | カテゴリ |

## 許可されたテーブル

AIが参照できるのは以下のテーブルのみ：
- members
- card_transactions

**それ以外のテーブルへのアクセスは禁止**
```

### Step 4: skills/business-rules.md を作成

ビジネスルールを固定化することで、AIによる「誤った解釈」を防ぎます。


```markdown
# Business Rules

## 許可された軸（ディメンション）

| 軸名 | 対応カラム | 許可値 |
|------|-----------|--------|
| 年代 | age_group | '20s', '30s', '40s', '50s+' |
| 会員ステージ | member_stage | 'bronze', 'silver', 'gold', 'platinum' |

## 許可された指標（メトリクス）

| 指標名 | 計算式 | 説明 |
|--------|--------|------|
| カード利用金額 | SUM(amount) | 期間内の合計利用金額 |
| 利用回数 | COUNT(transaction_id) | 期間内の取引回数 |
| 平均利用金額 | AVG(amount) | 1回あたり平均利用額 |

## 期間指定ルール

- 「直近3ヶ月」→ `WHERE transaction_date >= DATE_SUB(CURRENT_DATE, INTERVAL 3 MONTH)`
- 「2024年」→ `WHERE YEAR(transaction_date) = 2024`

**ユーザーが未定義の指標や期間を指定した場合は、SQLを生成せずエラーメッセージを返す**
```

### Step 5: CLAUDE.mdを設定

`CLAUDE.md` は全セッションで読み込まれる設定ファイルです。Treasure AI Studio上に直接編集できるエディターはないため、Project内のチャットでTAISに以下のように指示してください：

> 「このプロジェクトの `CLAUDE.md` に以下の内容を書き込んでください：
{以下の内容を貼り付けてください}」



```markdown
# Project: Customer Journey Analysis

このプロジェクトでは、顧客行動データからジャーニー分析を行います。

## Data Schema
@import skills/data-schema.md

## Business Rules  
@import skills/business-rules.md

## Guidelines

- **AIの役割**: ユーザーの自然言語リクエストから条件（年代、期間、指標）を抽出
- **システムの役割**: 事前定義されたSQLテンプレートに条件を差し込んで実行
- SQLの構造（JOIN、GROUP BY、集計ロジック）は固定化されており、AIが自由に変更してはいけない
```

> **補足**: `@import` はプロジェクト内の全ファイルを自動で読み込むわけではありません。ここに明示的に指定したファイルだけをロードします。Step 3・4で作成したファイルのパスと一致していることを確認してください。


![CLAUDE.mdの編集画面](/assets/03-claude-md-import.ef315c1f71bb1edc1deb796d10b4fca54f246bac2a2bddcf1be1f5e51fd4a6e0.94e46156.png)

## AIの役割を制限する設計思想

この固定化アプローチの核心は、**AIに任せる部分と任せない部分を明確に分離**することです。

### ✅ AIに任せる部分（解釈・設定）

- ユーザーの自然言語リクエストから条件を抽出
- 「年代別」「直近3ヶ月」などの条件を適切な値にマッピング
- 事前定義された「6つの業務メニュー」から適切なシナリオを判定


### ❌ AIに任せない部分（ロジック構築）

- 参照するテーブルやJOIN方法を毎回自由に決める
- 新しいKPIや独自の計算式を勝手に作成する
- 定義されていないカラムや属性を使う
- ルール外のSQLを生成してそのまま実行する


## ベストプラクティス

### 1. SQLテンプレートの型固定化

これは**任意**のテクニックです。最初から必須ではありませんが、以下のような状況になったときに活用すると効果的です：

- 同じ質問をしても集計結果がセッションごとにブレる
- 特定の分析が繰り返し失敗する
- 特定の条件のレコードを毎回集計から除外したい


`skills/business-rules.md` にSQLテンプレートを記載することで、AIが参照する構造を固定化し、より安定したクエリ生成が期待できます：


```markdown
## クロス集計SQLテンプレート

```sql
SELECT
  {縦軸},
  {横軸},
  {集計指標}
FROM {決められた参照表}
WHERE {決められた期間条件}
GROUP BY {縦軸}, {横軸}
```

**{} 部分のみをAIが差し替える。それ以外は変更不可**
```

### 2. マスター定義による3段階のガードレール

以下の「3つの防波堤」を実装します。バリデーションルールのブロックを `CLAUDE.md` にコピーして追記してください。

**防波堤1: データ範囲の限定**

- 業務シナリオごとに参照可能なテーブルを物理的に制限
- 例: クロス集計Agentには `members` と `card_transactions` のみアクセス許可


**防波堤2: マスター定義済み項目のみ利用**

- AIは独自解釈せず、事前定義した「軸・属性マスター」とユーザー指示をマッピングするのみ


**防波堤3: 定義外リクエストの実行停止**

- 指定項目が存在しない、条件が曖昧、想定外の組み合わせ → SQL生成せず停止し、ユーザーにガイドを返す


Project内のチャットでTAISに以下のように指示してください：

> 「このプロジェクトの `CLAUDE.md` の末尾に以下の内容を追記してください：
{以下の内容を貼り付けてください}」



```markdown
## バリデーションルール

実行前に以下をチェック：
1. 抽出した「年代」「会員ステージ」が許可された軸マスターに存在するか？
2. 「カード利用金額」が定義済み指標か？
3. 期間「直近3ヶ月」が許可された範囲か？
4. 外部エクスポートは許可された形式か？

**1つでもNGなら実行停止し、ユーザーに差し戻す**
```

### 3. memory/decisions.md で設計判断を記録

**（任意）** このファイルは新規プロジェクトでは必須ではありません。運用が始まり、ルールの **「なぜそうなったか」** という背景・経緯を残したくなったときに活用してください。

`decisions.md` に記録すると有効なケース：

- 特定の計算方法を選んだ理由
- 過去の分析で失敗したこととその対処
- スキーマやルールファイルには書けない文脈的な情報


注意点：ルールそのものが変わった場合は `decisions.md` に追記するのではなく、`business-rules.md` や `data-schema.md` 本体を更新してください。また、記載が増えすぎるとAIが部分的に無視することがあるため、重要な判断のみを簡潔に残すことを推奨します。


```markdown
# Design Decisions

## 2026-05-20: 「平均」の計算を member 単位に統一

**背景**: 当初は transaction 単位で AVG(amount) を計算していたが、営業部から「会員単位の平均」が必要と指摘。

**決定**: 
- `AVG(amount)` → `SUM(amount) / COUNT(DISTINCT member_id)`
- business-rules.md の指標定義を更新

**理由**: 1人で100回利用した場合と100人が1回ずつ利用した場合を区別するため
```

## まとめ

Treasure AI StudioのProject機能を使うことで、以下のような点でより便利に製品をご利用いただける方法を紹介しました：

1. **一貫性**: 全チャットで同じデータスキーマ・ビジネスルールを共有
2. **安全性**: AIの自由度を制限し、誤ったSQL生成を構造的に防止
3. **効率性**: 毎回の説明が不要になり、施策スピードが向上