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

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

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

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

pip install anthropic

# Command: review

你正在执行代码审查。

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

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

# Agent: senior-engineer

你是务实的资深工程师。

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

# Mode: risk-first

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

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

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()

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'

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

# Command: plan

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

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

# Mode: step-by-step

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

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

# Command: debug

你正在做系统化调试。

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

# Mode: concise

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

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

export ANTHROPIC_API_KEY='你的 key'

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")

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

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'