# 用 Markdown 行为文件搭建个人 AI 工作流：一个 SuperClaude 风格实践教程

- 原文：<https://www.marktechpost.com/2026/05/23/build-a-superclaude-framework-workflow-with-commands-agents-modes-and-session-memory/>
- 来源摘要：`/home/lin/.hermes/projects/hermes-gsummary-workflow/runs/outputs/20260525-095057-Build-a-SuperClaude-Framework-Workflow-with-Commands,-Agents,-Modes,-and-Session-61989-325372360-summary.md`
- 提取边界：原文主要展示 Python + Anthropic API + SuperClaude Markdown 资产的 PoC。本文面向个人实践，先给出离线可跑的最小闭环，再给出真实 API 接入骨架；后半部分为实践补充，不声称来自原文逐字内容。

## 1. 你要做成什么

目标不是复刻一个完整 agent 平台，而是做一个个人可维护的“行为文件驱动 AI 工作流”：

1. 把常用任务拆成 Markdown 行为文件：命令、角色、模式。
2. 每次调用模型前，按任务组合这些行为文件，拼成系统提示词。
3. 保留会话历史，支持中断后恢复。
4. 先用离线 mock 验证流程，再替换成真实模型 API。

适合场景：

- 你经常让 AI 做代码审查、方案拆解、调试分析、写文档。
- 你不想每次都重新写一大段提示词。
- 你希望不同任务有不同“执行契约”，而不是靠临场口头提醒。

不适合场景：

- 你只偶尔问几个简单问题。
- 你希望一开始就全自动改代码、部署、发消息。
- 你还没有明确的高频任务类型。

## 2. 最小架构

本教程使用 3 类 Markdown 资产：

- `commands/`：任务流程，例如 `review`、`plan`、`debug`。
- `agents/`：角色视角，例如 `senior-engineer`、`security-reviewer`。
- `modes/`：输出约束，例如 `concise`、`step-by-step`、`risk-first`。

一次调用的上下文结构：

```text
基础系统规则
+ 选中的 command Markdown
+ 选中的 agent Markdown
+ 选中的 mode Markdown
+ 用户输入
+ 历史记录（可选）
```

先不要引入复杂路由器。个人实践版只需要显式指定：

```bash
python personal_ai_workflow.py --command review --agent senior-engineer --mode risk-first "请审查这个函数"
```

## 3. 第一步：创建项目结构

```bash
mkdir -p personal-ai-workflow/{commands,agents,modes,sessions}
cd personal-ai-workflow
python3 -m venv .venv
source .venv/bin/activate
```

如果你要接真实 Anthropic API，再安装依赖：

```bash
pip install anthropic
```

先做离线 mock 时，不需要任何第三方依赖。

## 4. 第二步：写 3 个行为文件

### 4.1 命令：代码审查

创建 `commands/review.md`：

```markdown
# Command: review

你正在执行代码审查。

必须检查：
- 正确性：代码是否满足需求。
- 安全性：是否有注入、泄密、权限绕过风险。
- 可维护性：命名、边界、异常处理是否清晰。
- 测试：是否有必要的单元测试或回归测试。

输出格式：
1. 结论：通过 / 有条件通过 / 不通过
2. 阻断问题：必须修复的问题
3. 重要建议：值得修复但不阻断的问题
4. 可忽略建议：锦上添花的问题
```

### 4.2 角色：资深工程师

创建 `agents/senior-engineer.md`：

```markdown
# Agent: senior-engineer

你是务实的资深工程师。

偏好：
- 简单够用优先。
- 不过度设计。
- 先指出真实风险，再给建议。
- 不为了显得专业而引入不必要组件。
```

### 4.3 模式：风险优先

创建 `modes/risk-first.md`：

```markdown
# Mode: risk-first

回答时先列风险，再列改进建议。

规则：
- 高风险放前面。
- 不确定时标注“需要验证”。
- 不要把风格问题伪装成严重问题。
```

## 5. 第三步：实现离线最小闭环

创建 `personal_ai_workflow.py`：

```python
from __future__ import annotations

import argparse
import json
from dataclasses import dataclass, asdict
from pathlib import Path

ROOT = Path(__file__).parent
SESSIONS = ROOT / "sessions"


@dataclass
class Message:
    role: str
    content: str


class PersonalWorkflow:
    def __init__(self, session_name: str = "default") -> None:
        self.session_path = SESSIONS / f"{session_name}.json"
        self.history: list[Message] = self.load_history()

    def load_asset(self, kind: str, name: str | None) -> str:
        if not name:
            return ""
        path = ROOT / kind / f"{name}.md"
        if not path.exists():
            raise FileNotFoundError(f"missing {kind} asset: {path}")
        return path.read_text(encoding="utf-8")

    def build_system_prompt(
        self,
        command: str | None,
        agent: str | None,
        modes: list[str],
    ) -> str:
        parts = [
            "你是一个由本地 Markdown 行为文件约束的个人 AI 助手。",
            "<workflow>",
        ]
        parts.append(self.load_asset("commands", command))
        parts.append(self.load_asset("agents", agent))
        for mode in modes:
            parts.append(self.load_asset("modes", mode))
        parts.append("</workflow>")
        return "\n\n".join(part for part in parts if part.strip())

    def load_history(self) -> list[Message]:
        if not self.session_path.exists():
            return []
        data = json.loads(self.session_path.read_text(encoding="utf-8"))
        return [Message(**item) for item in data]

    def save_history(self) -> None:
        SESSIONS.mkdir(exist_ok=True)
        payload = [asdict(item) for item in self.history]
        self.session_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")

    def mock_model_call(self, system_prompt: str, user_prompt: str) -> str:
        return (
            "[MOCK 输出]\n"
            "已加载行为文件。真实接入模型前，请检查下面的系统提示词是否符合预期。\n\n"
            f"--- SYSTEM PROMPT ---\n{system_prompt}\n\n"
            f"--- USER PROMPT ---\n{user_prompt}\n"
        )

    def run(
        self,
        user_prompt: str,
        command: str | None,
        agent: str | None,
        modes: list[str],
        remember: bool,
    ) -> str:
        system_prompt = self.build_system_prompt(command, agent, modes)
        output = self.mock_model_call(system_prompt, user_prompt)
        if remember:
            self.history.append(Message(role="user", content=user_prompt))
            self.history.append(Message(role="assistant", content=output))
            self.save_history()
        return output


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    parser.add_argument("prompt")
    parser.add_argument("--command")
    parser.add_argument("--agent")
    parser.add_argument("--mode", action="append", default=[])
    parser.add_argument("--session", default="default")
    parser.add_argument("--no-remember", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    workflow = PersonalWorkflow(session_name=args.session)
    output = workflow.run(
        user_prompt=args.prompt,
        command=args.command,
        agent=args.agent,
        modes=args.mode,
        remember=not args.no_remember,
    )
    print(output)


if __name__ == "__main__":
    main()
```

## 6. 第四步：跑通第一个用例

执行：

```bash
python personal_ai_workflow.py \
  --command review \
  --agent senior-engineer \
  --mode risk-first \
  --session code-review-demo \
  '请审查这个 Python 函数：def add(a,b): return a+b'
```

预期输出应该包含：

```text
[MOCK 输出]
已加载行为文件。
--- SYSTEM PROMPT ---
# Command: review
# Agent: senior-engineer
# Mode: risk-first
--- USER PROMPT ---
请审查这个 Python 函数：def add(a,b): return a+b
```

验收标准：

- 能看到 `commands/review.md` 的内容。
- 能看到 `agents/senior-engineer.md` 的内容。
- 能看到 `modes/risk-first.md` 的内容。
- `sessions/code-review-demo.json` 被创建。
- session 文件中有 user 和 assistant 两条记录。

如果这里没跑通，不要接 API。先修本地资产加载和历史保存。

## 7. 第五步：增加第二个个人用例：计划拆解

创建 `commands/plan.md`：

```markdown
# Command: plan

你正在把一个目标拆成可执行计划。

要求：
- 先写边界：做什么，不做什么。
- 再拆成 3–7 个小步骤。
- 每一步必须有验收标准。
- 不要默认引入新工具或新依赖。
```

创建 `modes/step-by-step.md`：

```markdown
# Mode: step-by-step

输出必须按步骤组织。
每一步包含：目标、操作、验收标准、失败处理。
```

执行：

```bash
python personal_ai_workflow.py \
  --command plan \
  --agent senior-engineer \
  --mode step-by-step \
  --session planning-demo \
  '我想把每周读到的技术文章整理成个人知识卡片，请给我一个一周内能完成的实践计划。'
```

预期结果：

- 输出中包含“边界”。
- 每一步有验收标准。
- 没有直接建议上复杂知识库、数据库、自动化平台。

## 8. 第六步：增加第三个个人用例：调试复盘

创建 `commands/debug.md`：

```markdown
# Command: debug

你正在做系统化调试。

流程：
1. 复述现象。
2. 列出已知事实。
3. 给出 2–4 个假设。
4. 为每个假设设计最小验证步骤。
5. 验证前不要直接改代码。
```

创建 `modes/concise.md`：

```markdown
# Mode: concise

保持简洁。
优先输出可验证步骤，不输出长篇背景解释。
```

执行：

```bash
python personal_ai_workflow.py \
  --command debug \
  --agent senior-engineer \
  --mode concise \
  --session debug-demo \
  '我的脚本昨天能运行，今天报 ModuleNotFoundError: requests，应该怎么排查？'
```

验收标准：

- 先要求确认 Python 环境、虚拟环境、依赖安装位置。
- 不直接让你重装系统或删除环境。
- 每个假设都有验证命令。

## 9. 第七步：替换成真实 Anthropic API（可选）

确认 mock 路径稳定后，再加真实模型调用。不要把 API Key 写进代码。

设置环境变量：

```bash
export ANTHROPIC_API_KEY='你的 key'
```

在 `personal_ai_workflow.py` 中新增一个真实调用方法：

```python
import os
from anthropic import Anthropic


def anthropic_call(system_prompt: str, user_prompt: str) -> str:
    if not os.environ.get("ANTHROPIC_API_KEY"):
        raise RuntimeError("ANTHROPIC_API_KEY is not set")

    client = Anthropic()
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1600,
        system=system_prompt,
        messages=[{"role": "user", "content": user_prompt}],
    )
    return "".join(block.text for block in response.content if block.type == "text")
```

然后把 `mock_model_call()` 替换为可切换模式：

```python
if use_real_model:
    output = anthropic_call(system_prompt, user_prompt)
else:
    output = self.mock_model_call(system_prompt, user_prompt)
```

个人实践建议：默认仍保留 mock 模式。真实调用前先打印系统提示词，确认没有加载错行为文件。

## 10. 个人实践的安全边界

不要一开始做这些：

- 自动改项目文件。
- 自动执行 shell 命令。
- 自动提交 Git。
- 自动调用付费 API 循环重试。
- 自动写入长期知识库。

推荐的安全推进顺序：

1. 只读建议：模型只输出建议，不动文件。
2. 生成候选补丁：模型输出 diff，但由你手动应用。
3. 受限写入：只允许写临时目录或草稿目录。
4. 人工确认后执行：任何真实副作用前都需要确认。

## 11. 一周实践路线

### Day 1：只做行为文件

交付物：

- `commands/review.md`
- `commands/plan.md`
- `commands/debug.md`
- `agents/senior-engineer.md`
- `modes/risk-first.md`
- `modes/step-by-step.md`
- `modes/concise.md`

验收：你能说清每个文件什么时候用。

### Day 2：跑通 mock 引擎

交付物：

- `personal_ai_workflow.py`
- 3 个 session JSON 示例

验收：每个命令组合都能正确拼接系统提示词。

### Day 3：整理 3 个真实个人任务

建议任务：

- 审查一段真实代码。
- 拆一个一周内的小计划。
- 复盘一次真实报错。

验收：每个任务都有输入、输出、你是否采纳、原因。

### Day 4：接入真实模型

只做一次真实调用，不做自动化循环。

验收：真实输出比 mock 更有用，且行为文件约束被遵守。

### Day 5：补失败处理

必须覆盖：

- 行为文件不存在。
- API Key 未设置。
- 模型返回空输出。
- session JSON 损坏。

### Day 6：沉淀个人模板

把高频任务整理成固定命令：

```bash
alias ai-review='python personal_ai_workflow.py --command review --agent senior-engineer --mode risk-first'
alias ai-plan='python personal_ai_workflow.py --command plan --agent senior-engineer --mode step-by-step'
alias ai-debug='python personal_ai_workflow.py --command debug --agent senior-engineer --mode concise'
```

### Day 7：做一次复盘

复盘问题：

- 哪个 command 最常用？
- 哪个 mode 没有价值？
- 哪些输出仍然太泛？
- 是否真的减少了重复提示词？
- 是否需要新增一个行为文件，而不是改代码？

## 12. 常见坑与处理

### 坑 1：行为文件写得太长

表现：模型忽略重点，输出变散。

处理：每个行为文件先控制在 30 行以内，只保留硬规则。

### 坑 2：command、agent、mode 职责混在一起

表现：多个文件互相重复甚至冲突。

处理：

- command 写“任务流程”。
- agent 写“判断视角”。
- mode 写“输出约束”。

### 坑 3：过早做自动化执行

表现：模型还不稳定，就开始写文件、跑命令、改配置。

处理：先保留人工确认。个人实践的第一目标是降低重复提示词，不是让 AI 自主接管电脑。

### 坑 4：session 越积越长

表现：模型开始引用过期背景。

处理：每个任务单独 session。任务结束后写一段人工摘要，而不是无限保存所有对话。

## 13. 最小可用标准

这个个人工作流达到下面标准就够用：

- 你有 3 个稳定 command。
- 你有 1–2 个稳定 agent。
- 你有 2–3 个稳定 mode。
- 每次调用能明确显示当前加载的 command / agent / mode。
- session 能保存和恢复。
- 真实副作用仍由你确认。

不要急着做复杂路由、插件系统、多模型调度、自动文件修改。先把个人高频场景跑顺。