📚 AI 工程与智能体教程站

English

简体中文

English

简体中文

Chapter 20 · Workflow Philosophy and Team Practices ​

Chapter goals: Deep-read pi's design philosophy; understand the tradeoffs behind "minimal core + on-demand add-ons";落地 a directly copyable team workflow: context file norms, template/skill/extension combinations, session sharing, and a rollout checklist.

20.1 Philosophy Deep-Dive: Six "Do Not Build In" Declarations ​

pi's READMEdevotes an entire section to声明 what it deliberately does not内置, each with a明确替代路径:

Not built inOfficial alternative
No MCPWrite a README for CLI tools to use as a skill; or写 an extension提供 MCP support
No sub-agentsSpawn multiple pi instances via tmux; or build自建 via extension; or install a第三方包
No permission popupsRun in a container; or use an extension实现确认流适配 your environment
No plan modeWrite the plan to a file; or extension implements; or install a包
No built-in to-dos"They confuse the model" — use a TODO.md file, or extension implements
No background bashUse tmux;获得完整可观测性与直接交互

Behind these six is one principle: whenever a workflow preference分歧 across teams, don't焊死 it in the core. Built-in = deciding for you = an unused feature becomes a burden. pi chooses to压 the core to minimum (model + 7 tools + session tree) and leave "how sub-agents work, how plans管" to the extension and包 ecosystem.

Contrasting with "bloatware" tools

This doesn't mean these capabilities不该 exist — rather they should exist as replaceable components. Don't like the官方 default? Install someone else's包, or have pi itself写 you an extension —这正是前几章 Extensions/Skills/Packages的意义.

20.2 A Recommended Team Combination ​

Based on the previous nineteen chapters, here is a verified minimal combination (all落在 the repo and走 with the code):

text
repo/
├── AGENTS.md                  # Project conventions (see next section for details)
├── .pi/
│   ├── settings.json          # Project-level settings (defaultProjectTrust etc.管 globally by the user)
│   ├── prompts/
│   │   └── review.md          # /review prompt template
│   ├── skills/
│   │   └── deploy/SKILL.md    # Deployment流程 skill
│   └── extensions/
│       └── guardrails.ts      # Dangerous command confirmation extension

Division of labor logic:

  • AGENTS.md governs "what this project is, what the rules are" —静态, same for everyone;
  • Prompt Templates govern高频指令标准化 — actions统一措辞 like /review, /release-notes;
  • Skills govern多步流程知识 — deployment, release这类有固定顺序的操作写成技能, the model executes per SKILL.md;
  • Extensions govern行为约束与 UI — e.g.拦截 rm -rf类 commands requiring二次确认 (your自建 permission popup);
  • 个人差异 (themes, thinking level, API keys) go in the user global dir; not into the repo.

20.3 Context File Engineering: AGENTS.md Writing Norms ​

Loading rules回顾 (详见 usage docs): at startup load from ~/.pi/agent/AGENTS.md (global) → each layer of parent dirs from the current directory → current directory逐层; if AGENTS.override.md exists in the same directory it 取代 that directory's AGENTS.md/CLAUDE.md. To replace the system prompt entirely use .pi/SYSTEM.md; to仅 append use .pi/APPEND_SYSTEM.md.

A good project AGENTS.md应包含四块内容 (also the官方建议的用途: project conventions, commands, security rules, preferences):

markdown
# Project Conventions

## Build and Test
- Package manager: pnpm; do not use npm install
- Test command: pnpm test --filter <pkg>; full tests exceed 5 minutes —禁止主动全跑

## Code Style
- Commit messages follow Conventional Commits
- TypeScript strict mode;禁用 any assertions

## Security Red Lines
- Do not modify any files under .github/workflows/
- DB migrations必须人工审查后才执行
- Credentials走 env vars only; flag hardcoded secrets immediately

## Known Pitfalls
- src/legacy/ is待下线 code; do not refactor it

Writing要诀: specific,可判定,少量高价值. "Write good comments"这种模糊要求没有用; "禁止全量测试"这种硬约束最有用. Context files占 token; keep to one to two screens.

20.4 Session Sharing and Team Learning ​

pi turns "how to use agents" itself into沉淀的知识:

bash
# In interactive mode: export as HTML / upload to a private GitHub gist for a shareable link
/export review-demo.html
/share

# CLI: export any historical session as a web archive
pi --export ~/.pi/agent/sessions/--path--/2024_xxx.jsonl out.html

Open-source folks还可以用社区的 badlogic/pi-share-hf publish sessions as Hugging Face datasets —真实开发会话对 prompt, tool, and evaluation研究都很有价值. Inside a team建议: archive every疑难 bug攻坚 session via /share into the wiki;新 members learn by reading "how experts协作 with agents" — much faster than reading docs.

20.5 Team Rollout Checklist ​

The顺序清单 for推行 pi workflows in a team从零:

  1. [ ] 统一版本: upgrade everyone to the same pi version (pi update --self); avoid behavior漂移;
  2. [ ] 全局底线: each person配置好 provider credentials (/login or env vars);关闭 telemetry as needed;
  3. [ ] 仓库接入: commit AGENTS.md (start with build commands and security red lines);
  4. [ ] 标准动作模板化:做成 .pi/prompts/ the高频指令 like code review, release notes;
  5. [ ] 流程技能化: deployment/troubleshooting SOPs写成 skills; let新 hands walk the专家 path;
  6. [ ] 行为护栏扩展化: dangerous command确认, output filtering etc. covered by extensions;
  7. [ ] 隔离策略:约定 which tasks必须跑 in containers (Chapter 19); CI统一用 -na + explicit args;
  8. [ ] 知识回流:定期 /share典型 sessions; iterate the "known pitfalls"区 of AGENTS.md.

20.6 Chapter Summary ​

  • Six "do not build in" share one philosophy: contentious workflow decisions不进 the core;留给 extensions/skills/packages;
  • Team combination formula: AGENTS.md governs conventions + prompts govern高频指令 + skills govern流程 + extensions govern约束; personal prefs留全局;
  • AGENTS.md要具体可判定; cover conventions/commands/red lines/known pitfalls四块;控制篇幅;
  • /export, /share, pi --export让协作过程本身可归档、可学习;
  • Rollout顺序: version统一 → global credentials → repo接入 → templates → skills → guardrails → isolation → knowledge回流.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is pi's官方 reason for not内置 to-do functionality?

2. When both AGENTS.md and AGENTS.override.md exist in the same directory, pi does?

3. Regarding the division of labor among resource types in the team combination, which is correct?

4. To归档 a完整的疑难 bug troubleshooting session for the team to learn, the most合适的做法 is?

🛠️ Hands-on Practice ​

  1. Draft the first version of AGENTS.md for your team repo:只写构建命令, three security red lines, and two known pitfalls; keep under 30 lines; then verify pi真正遵守了每一条.
  2. Pick the most frequentlyasked操作 in your team (e.g. "how to起 the full environment locally");做成 a prompt template or skill; have two colleagues实测 and iterate based on feedback. 3.完全走一遍第 20.5 节检查单的前 4 项;记录每一项在你的团队中遇到的实际阻力与解决办法.