Agent SOP 完整教學

 1from pathlib import Path
 2
 3_sops_dir = Path(__file__).parent / "sops"
 4
 5for _md_file in _sops_dir.glob("*.sop.md"):
 6    if _md_file.is_file():
 7        # 將檔名轉為合法的 Python 識別符
 8        # 例如 code-assist.sop.md → code_assist
 9        _attr_name = (
10            _md_file.stem.removesuffix(".sop").replace("-", "_").replace(".", "_")
11        )
12        _content = _md_file.read_text(encoding="utf-8")
13
14        # 將 SOP 內容註冊為模組屬性
15        globals()[_attr_name] = _content
16
17        # 同時建立 wrapper function，產生 XML 格式
18        def _make_wrapper(content, name):
19            def wrapper(user_input: str = "") -> str:
20                return f"""<agent-sop name="{name}">
21<content>
22{content}
23</content>
24<user-input>
25{user_input}
26</user-input>
27</agent-sop>"""
28            return wrapper
29
30        globals()[f"{_attr_name}_with_input"] = _make_wrapper(_content, _sop_name)

 1from mcp.server.fastmcp import FastMCP
 2
 3def run_mcp_server(sop_paths: str | None = None):
 4    mcp = FastMCP("agent-sop-prompt-server")
 5    registered_sops = set()  # 追蹤已註冊的 SOP，實現 first-wins 行為
 6
 7    def register_sop(name: str, content: str, description: str):
 8        if name not in registered_sops:
 9            registered_sops.add(name)
10
11            def make_prompt_handler(sop_name: str, sop_content: str):
12                def get_prompt(user_input: str = "") -> str:
13                    return f"""Run this SOP:
14<agent-sop name="{sop_name}">
15<content>
16{sop_content}
17</content>
18<user-input>
19{user_input}
20</user-input>
21</agent-sop>"""
22                return get_prompt
23
24            # 註冊為 MCP prompt
25            mcp.prompt(name=name, description=description)(
26                make_prompt_handler(name, content)
27            )
28
29    # 外部 SOP 優先載入（higher precedence）
30    if sop_paths:
31        external_directories = expand_sop_paths(sop_paths)
32        external_sops = load_external_sops(external_directories)
33        for sop in external_sops:
34            register_sop(sop["name"], sop["content"], sop["description"])
35
36    # 內建 SOP 後載入（lower precedence）
37    sops_dir = Path(__file__).parent / "sops"
38    for md_file in sops_dir.glob("*.sop.md"):
39        # ... 略
40        register_sop(prompt_name, sop_content, description)
41
42    mcp.run()

1brew install strands-agents-sops

1pip install strands-agents-sops

1uv pip install strands-agents-sops

1git clone https://github.com/strands-agents/agent-sop.git
2cd agent-sop/python
3pip install -e .

1# 確認 CLI 可用
2strands-agents-sops --help
3
4# 啟動 MCP Server 測試
5strands-agents-sops mcp
6# 應看到 MCP server 啟動訊息

1pip install strands-agents strands-agents-tools strands-agents-sops

1{
2  "mcpServers": {
3    "agent-sops": {
4      "command": "strands-agents-sops",
5      "args": ["mcp"],
6      "env": {}
7    }
8  }
9}

1{
2  "mcpServers": {
3    "agent-sops": {
4      "command": "strands-agents-sops",
5      "args": ["mcp"]
6    }
7  }
8}

1{
2  "mcpServers": {
3    "agent-sops": {
4      "command": "strands-agents-sops",
5      "args": ["mcp", "--sop-paths", "~/my-sops:/team/shared-sops"],
6      "env": {}
7    }
8  }
9}

1# 從 SOP 產生 Cursor 指令
2strands-agents-sops commands --type cursor
3
4# 指定輸出目錄
5strands-agents-sops commands --type cursor --output-dir .cursor/commands
6
7# 含自訂 SOP
8strands-agents-sops commands --type cursor --sop-paths ~/my-sops

 1from strands import Agent
 2from strands_tools import editor, shell
 3from strands_agents_sops import code_assist
 4
 5# 建立 Agent，以 code_assist SOP 作為系統指令
 6agent = Agent(
 7    system_prompt=code_assist,    # SOP 的 Markdown 字串直接注入
 8    tools=[editor, shell]         # 提供檔案編輯和 shell 執行工具
 9)
10
11# 啟動 SOP 流程
12agent("Start code-assist sop")
13
14# 互動式循環：使用者逐步提供參數和確認
15while True:
16    user_input = input("\nInput: ")
17    agent(user_input)

 1from strands import Agent
 2from strands_tools import editor, shell
 3from strands_agents_sops import code_assist_with_input
 4
 5# 建立基礎 Agent（不預設 SOP）
 6agent = Agent(tools=[editor, shell])
 7
 8# 使用 _with_input wrapper，將使用者需求一次帶入
 9response = agent(
10    code_assist_with_input(
11        "Implement a REST API endpoint for user authentication "
12        "using JWT tokens with refresh token rotation"
13    )
14)

1<agent-sop name="code-assist">
2<content>
3[完整的 code-assist.sop.md 內容]
4</content>
5<user-input>
6Implement a REST API endpoint for user authentication...
7</user-input>
8</agent-sop>

 1# PR Review
 2
 3## Overview
 4This SOP guides AI agents through a structured pull request review process,
 5focusing on code quality, security, performance, and adherence to team standards.
 6
 7## Parameters
 8- **pr_url** (required): The URL or identifier of the pull request to review
 9- **review_focus** (optional, default: "general"): Focus area - "general", "security", "performance"
10- **codebase_context** (optional): Path to relevant architecture docs
11
12## Steps
13
14### 1. Context Gathering
15Retrieve the PR diff, commit messages, and related issue descriptions.
16
17**Constraints:**
18- You MUST read the complete diff before making any assessment
19- You MUST identify the PR's stated purpose from the description or linked issues
20- You MUST NOT review files unrelated to the PR's changes
21- You SHOULD check if the PR affects critical paths (auth, payments, data migration)
22
23### 2. Structural Review
24Evaluate the overall design and architecture of the changes.
25
26**Constraints:**
27- You MUST verify the changes align with existing architecture patterns
28- You SHOULD flag any new dependencies or external service integrations
29- You MAY suggest alternative approaches if the current design has scalability concerns
30- You MUST NOT suggest rewrites of working code unless there is a clear defect
31
32### 3. Line-by-Line Review
33Perform detailed code inspection.
34
35**Constraints:**
36- You MUST check for common vulnerabilities (SQL injection, XSS, SSRF)
37- You MUST verify error handling covers edge cases
38- You SHOULD identify any code that violates DRY principles
39- You SHOULD check test coverage for new code paths
40- You MAY suggest style improvements but MUST NOT block on style alone
41
42### 4. Summary and Recommendation
43Provide a structured review summary.
44
45**Constraints:**
46- You MUST categorize findings as CRITICAL, HIGH, MEDIUM, or LOW severity
47- You MUST provide an overall recommendation: APPROVE, REQUEST_CHANGES, or COMMENT
48- You MUST include actionable next steps for each finding
49- You SHOULD acknowledge well-written code sections

1# 1. 透過 MCP Server 載入
2strands-agents-sops mcp --sop-paths ~/my-sops
3
4# 2. 轉為 Cursor 指令
5strands-agents-sops commands --type cursor --sop-paths ~/my-sops
6
7# 3. 轉為 Agent Skill
8strands-agents-sops skills --output-dir ./skills --sop-paths ~/my-sops

 1from strands import Agent
 2from strands_tools import editor, shell, http_request
 3from strands_agents_sops import pdd
 4
 5# PDD 需要更多工具來做研究和文件操作
 6agent = Agent(
 7    system_prompt=pdd,
 8    tools=[editor, shell, http_request]
 9)
10
11# 啟動 PDD — Agent 會引導你完成以下階段：
12# 1. Create Project Structure    → 建立 .agents/planning/ 目錄結構
13# 2. Initial Process Planning    → 決定先做 requirements 還是 research
14# 3. Requirements Clarification  → 一次問一個問題，逐步釐清需求
15# 4. Research                    → 蒐集技術資訊、競品分析
16# 5. Design Creation             → 撰寫完整設計文件 + Mermaid 圖表
17# 6. Implementation Planning     → 拆解為可執行的實作步驟
18
19agent("Start PDD with rough idea: Build a real-time collaborative "
20      "markdown editor with conflict resolution")

 1.agents/
 2└── planning/
 3    └── 2026-06-18-collaborative-editor/
 4        ├── rough-idea.md              # 原始想法
 5        ├── idea-honing.md             # 需求釐清 Q&A
 6        ├── research/
 7        │   ├── existing-code.md       # 現有程式碼分析
 8        │   └── technologies.md        # 技術選型研究
 9        ├── design/
10        │   ├── system-design.md       # 系統設計文件
11        │   └── api-design.md          # API 設計
12        └── implementation/
13            └── plan.md                # 實作計畫 + checklist

1# 好的寫法 — 附帶理由
2- You MUST NOT delete files without confirmation because this could result in permanent data loss
3
4# 不好的寫法 — 缺少理由
5- You MUST NOT delete files

 1def load_external_sops(sop_directories: list[Path]) -> list[dict[str, Any]]:
 2    external_sops = []
 3    for directory in sop_directories:
 4        if not directory.exists():
 5            logger.warning(f"SOP directory does not exist: {directory}")
 6            continue
 7        for sop_file in directory.glob("*.sop.md"):
 8            sop_content = sop_file.read_text(encoding="utf-8")
 9            # 必須包含 ## Overview 段落，否則跳過
10            overview_match = re.search(
11                r"## Overview\s*\n(.*?)(?=\n##|\n#|\Z)", sop_content, re.DOTALL
12            )
13            if not overview_match:
14                logger.warning(f"No Overview section found in {sop_file}")
15                continue
16            # ...
17    return external_sops

 1# 1. MCP Server — 適用 Kiro CLI、Claude Code 等支援 MCP 的工具
 2strands-agents-sops mcp
 3
 4# 2. Agent Skills — 產生含 frontmatter 的 SKILL.md 檔案
 5strands-agents-sops skills --output-dir ./skills
 6
 7# 3. Cursor Commands — 產生 .cursor/commands/ 下的指令檔案
 8strands-agents-sops commands --type cursor
 9
10# 4. Rule Output — 輸出 SOP 撰寫格式規範
11strands-agents-sops rule

 1def _create_skill_file(output_path, skill_name, content, description):
 2    skill_dir = output_path / skill_name
 3    skill_dir.mkdir(parents=True, exist_ok=True)
 4
 5    frontmatter = f"""---
 6name: {skill_name}
 7description: {description}
 8---
 9
10"""
11    skill_file = skill_dir / "SKILL.md"
12    skill_file.write_text(frontmatter + content)

1                    +----- [3] code-task-generator ----+
2                    |    將 PDD plan 拆為 task 檔案     |
3                    |                                   v
4[1] codebase-summary → [2] pdd → [3] tasks → [4] code-assist
5    分析現有程式碼        設計規劃     任務拆解      TDD 實作

1# 完整指令參考
2strands-agents-sops --help
3
4# 子指令
5strands-agents-sops mcp [--sop-paths PATH]        # 啟動 MCP Server
6strands-agents-sops skills [--output-dir DIR]      # 產生 Agent Skills
7strands-agents-sops commands --type cursor         # 產生 Cursor 指令
8strands-agents-sops rule                           # 輸出 SOP 格式規範

1/strands-agents-sops:codebase-summary

1@codebase-summary

1# 直接 import SOP 內容
2from strands_agents_sops import code_assist, pdd, codebase_summary
3
4# 使用 with_input wrapper
5from strands_agents_sops import code_assist_with_input
6
7# 取得 SOP 格式規範
8from strands_agents_sops import get_sop_format

 1# 在 Kiro CLI 中
 2@codebase-summary
 3
 4# Agent 會：
 5# 1. 掃描整個 codebase 結構
 6# 2. 識別架構模式、技術堆疊、關鍵介面
 7# 3. 產生 Mermaid 圖表的系統架構圖
 8# 4. 輸出到 .agents/summary/
 9#    - index.md（導覽索引，AI 助手的入口點）
10#    - architecture.md（系統架構）
11#    - components.md（模組說明）
12#    - interfaces.md（API 與整合點）
13#    - workflows.md（關鍵流程）
14#    - AGENTS.md（AI 助手專用的 README）

 1from strands import Agent
 2from strands_tools import editor, shell
 3from strands_agents_sops import pdd, code_task_generator_with_input, code_assist
 4
 5# Phase 1: 設計規劃
 6design_agent = Agent(system_prompt=pdd, tools=[editor, shell])
 7design_agent("Build a rate limiter middleware with sliding window algorithm")
 8
 9# Phase 2: 任務拆解（從 PDD 的 plan.md 自動拆解）
10task_agent = Agent(system_prompt=code_task_generator_with_input(
11    ".agents/planning/2026-06-18-rate-limiter/implementation/plan.md"
12), tools=[editor, shell])
13task_agent("Generate tasks from this plan")
14
15# Phase 3: 逐任務 TDD 實作
16impl_agent = Agent(system_prompt=code_assist, tools=[editor, shell])
17impl_agent("Start code-assist sop for task: "
18           ".agents/tasks/2026-06-18-rate-limiter/step01/task-01.code-task.md")

1# 在 Kiro CLI 或 Claude Code 中
2@eval
3
4# Agent 會引導你完成：
5# 1. Setup — 驗證環境、建立 eval/ 目錄
6# 2. Plan — 設計評估策略（哪些面向、哪些指標）
7# 3. Generate Test Data — 自動或半自動產生測試案例（JSONL 格式）
8# 4. Execute — 跑評估腳本，收集結果
9# 5. Analyze — 分析結果、產生報告、提出改善建議

 1# SOP 標題
 2
 3## Overview
 4簡述用途和適用場景。
 5
 6## Parameters
 7- **param_name** (required): 必要參數說明
 8- **param_name** (optional, default: "value"): 選用參數說明
 9
10## Steps
11### 1. 步驟名稱
12自然語言描述。
13
14**Constraints:**
15- You MUST [必要行為]
16- You SHOULD [建議行為]
17- You MAY [選用行為]
18- You MUST NOT [禁止行為] because [理由]
19
20## Examples
21具體的輸入輸出範例。
22
23## Troubleshooting
24常見問題與解決方式。