---
name: coaching-ai-prompt-design
description: Design effective system prompts for conversational AI coaches — decision frameworks, depth progression, style modules, and segment-based response rendering. Use when improving or building coaching/mentoring/therapy chatbots.
---

# AI Coaching Prompt Design

## When to Use

- User complains AI coach responses feel stiff, repetitive, or like a parrot
- Building or refining a conversational coaching/mentoring bot
- Need to add "challenge" or depth progression to an LLM-based coach

## Core Insight

**Rigid output formats kill coaching quality.** A prompt that says "output exactly: reflection (30 chars) → question (30 chars)" produces a mechanical pattern. The fix is not tweaking the format — it's embedding a **decision framework** in the system prompt.

## Prompt Architecture

### 1. Persona + Philosophy (who are you?)

Give the coach an identity and core beliefs. NOT "you are a professional coach" — too generic. Instead:

```
你是一位经验丰富的成长教练。你不是顾问——不给建议、不开药方。
你的武器是提问、反映和挑战。你的目标是让客户看见自己看不见的东西。
```

### 2. Depth Progression (L1 → L5)

Define clear levels so the model knows WHERE it is and WHERE to go:

- **L1 共鸣**: Build safety. Reflect emotion, show understanding.
- **L2 澄清**: Get specifics. Who, what, when, how it felt.
- **L3 挑战**: Point out contradictions, avoidance patterns, untested assumptions.
- **L4 价值观**: Explore underlying beliefs and identity.
- **L5 行动**: Help define next steps (only at closing stage).

Key rule: **Don't jump from L1 to L3.** Each layer paves the way for the next.

### 3. Internal Decision Loop

Explicitly tell the model to reason BEFORE responding:

```
在生成回复前，快速评估：
- 当前对话在哪个深度层次？
- 客户的情绪状态是开放、防御还是回避？
- 有什么盲点/矛盾/未检验的假设没有被触及？
- 这一轮该「推」（深入）还是「托」（给空间）？
```

Then choose strategy: 深入 / 停留 / 挑战 / 视角转换

### 4. Segment-Based Output

Use typed segments instead of a single text blob. This lets the frontend render each segment with different timing and styling:

```json
{
  "segments": [
    {"type": "reflect", "content": "反映感受"},
    {"type": "challenge", "content": "指出矛盾（可选）"},
    {"type": "question", "content": "推动深入的问题"}
  ],
  "turn_type": "reflect_ask",
  "suggest_integrate": false
}
```

- `reflect`: Appears first, builds rapport
- `challenge`: Appears between reflect and question, with distinct visual styling (italic, left border)
- `question`: Appears last, pushes depth forward

### 5. Style Modules

Define 2-4 coaching styles with **concrete personality descriptions**, not abstract labels:

| Style | Persona | Key traits |
|-------|---------|------------|
| warm | 多年老友 | Soft entry for challenge, L1-L2 focused, own words for reflection |
| direct | 直爽教练 | Short sentences, no preamble, "你在骗自己" is fair game |
| quiet | 深夜对坐的朋友 | Few words, heavy silence, big open questions |
| curious | 人类探险家 | "如果…假设…", metaphors, curious about the "why" |

### 6. Show, Don't Just Tell

Include **two contrasting examples** in the prompt — one good, one bad. The model learns much more from contrast than from rules alone.

### 7. Language Bans

Explicitly forbid coaching-killer phrases:
- 你应该、我建议、我觉得你应该、其实你是、我分析
- 提问式建议 ("你有没有想过…" is still advice)

## Pitfalls

### "Changed the prompt but nothing happened"

**Symptom**: Built + restarted, but coach responses unchanged.

**Root cause**: An old process (started before the build) is still occupying the port. `next start` loads compiled code at startup — it does NOT hot-reload in production.

**Fix checklist**:
1. `ss -tlnp | grep <port>` — find ALL processes on the port
2. `ps -p <pid> -o lstart` — check start time vs build time
3. `kill -9 <all-pids>` — kill parent shell AND child node process
4. `ss -tlnp | grep <port>` — verify port is FREE (empty output)
5. Verify build has new code: `grep "key phrase" .next/server/chunks/*.js`
6. Start new process
7. Verify new PID is on port: `ss -tlnp | grep <port>`

### DeepSeek `json_object` requires the word "json" in the prompt

**Symptom**: API returns HTTP 400 with error `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'."`. The frontend shows generic error (e.g., "连接有点问题").

**Root cause**: DeepSeek (and potentially other providers) validates that when you set `response_format: { type: 'json_object' }`, the word "json" (case-insensitive) must appear somewhere in the system or user prompt. A well-crafted prompt that shows JSON examples but never actually says the word "json" will fail.

**Fix**: Always include a line like `你必须以 JSON 格式输出` or `输出 JSON 格式` in the system prompt. Check the compiled chunk (`grep json .next/server/chunks/*.js`) to confirm the word appears in the final prompt string.

### Model choice matters

`deepseek-v4-flash` for coaching → responses feel rushed. Upgrade to `deepseek-v4-pro` (or equivalent) for tasks requiring nuanced emotional reasoning and multi-step decision-making.

## Reference Files

- `references/icoach-implementation.md` — Concrete implementation in the icoach project (file paths, code structure)