独立开发者

作为独立开发者，PinableAgents 是你最强大的"虚拟搭档"。你不需要复杂的团队协作功能，核心目标是用最少的配置获得最大的生产力提升。推荐使用 do + essentials 模块组合，这两个模块覆盖了从需求分析到代码交付的完整流程。

推荐工作流

独立开发者的日常工作流建议围绕 do 流程展开。do 流程提供了一个轻量但完整的七阶段开发流程：探索代码库、理解需求、制定计划、实现代码、审查质量、测试验证、提交交付。对于简单任务，你可以直接使用 essentials 模块中的单一智能体完成。

配置模板

# ~/.pinable-agents/config.json（独立开发者推荐配置）
{
  "backend": "claude",
  "model": "claude-opus-4-6",
  "modules": ["do", "essentials"],
  "workflows": {
    "default": "do",
    "auto_commit": true,
    "auto_test": true
  },
  "quality_gates": {
    "strict_mode": false,
    "test_coverage": {
      "line_coverage_min": 60
    }
  },
  "skills": {
    "auto_detect": true,
    "budget_limit": 16384
  }
}

独立开发者最容易犯的错误是一开始就启用所有模块和最严格的质量门控。这会导致工作流执行时间过长，反而降低效率。从最简配置开始，当你感到某个环节需要更多支持时再逐步添加。

小型团队（2-5 人）

小型团队引入 PinableAgents 时，关键是建立共享的配置标准和清晰的角色分工。团队成员不再各自使用不同的 AI 工具和提示词，而是通过统一的工作流确保输出的一致性。

角色分配建议

角色 推荐工作流 职责
技术负责人 do + omo 架构设计、复杂问题调查、代码审查
全栈开发者 do + essentials 功能开发、Bug 修复、日常维护
初级开发者 essentials 在引导下完成任务，逐步熟悉工作流

共享配置

将 PinableAgents 的配置文件纳入版本控制，确保团队成员使用统一的设置。在项目根目录创建 .pinable-agents/ 目录，存放团队共享的配置、自定义技能和智能体定义。

# 项目级配置（优先于用户级配置）
# .pinable-agents/config.json
{
  "team": {
    "name": "awesome-team",
    "shared_skills": true,
    "shared_agents": true
  },
  "workflows": {
    "default": "do",
    "require_review": true,
    "review_assignee": "tech-lead"
  },
  "quality_gates": {
    "prd_score_threshold": 65,
    "test_coverage": {
      "line_coverage_min": 70,
      "branch_coverage_min": 55
    }
  }
}

代码审查集成

小型团队应该充分利用 PinableAgents 的代码审查能力来补充人工审查。推荐的流程是：智能体完成初步审查并生成报告，团队成员在此基础上进行二次审查，聚焦于智能体难以覆盖的业务逻辑和设计合理性。

# 在 Pull Request 流程中集成智能体审查
pinable-agents review --pr 42 --output markdown > review-report.md

# 审查报告会包含：
# - 代码质量评估（命名、复杂度、重复代码）
# - 安全隐患检查
# - 测试覆盖率分析
# - 改进建议（按优先级排序）

中型团队（5-15 人）

中型团队通常有更成熟的开发流程，需要 PinableAgents 与现有的敏捷开发实践深度集成。BMAD 工作流是中型团队的首选，它模拟了一个完整的 Scrum 团队角色结构。

BMAD 工作流与 Sprint 集成

BMAD 工作流中的智能体角色可以映射到 Scrum 团队的对应角色：

  • 产品经理智能体 - 辅助 PO 将用户需求转化为结构化的 PRD
  • 架构师智能体 - 辅助技术负责人进行架构设计和技术选型评估
  • 开发者智能体 - 在 Sprint 执行阶段编写代码实现
  • 审查者智能体 - 在 Sprint Review 前进行自动化质量检查

在 Sprint Planning 阶段，团队可以使用 BMAD 工作流的 PRD 阶段来快速生成和评估用户故事。在 Sprint 执行阶段，开发者使用 do 工作流完成各自的任务。在 Sprint Review 前，使用质量门控进行全面检查。

共享智能体库

中型团队应该建立团队级的智能体库，存放针对团队特定需求定制的智能体。例如，一个负责数据库变更审查的智能体，或一个专门生成 API 文档的智能体。

# .pinable-agents/agents/db-reviewer.yaml
name: db-reviewer
role: 数据库变更审查专家
expertise:
  - SQL 性能优化
  - 在线 DDL 策略
  - 数据一致性保障
review_checklist:
  - 是否有对应的回滚脚本
  - 大表变更是否使用 pt-online-schema-change
  - 索引变更是否经过执行计划分析
  - 是否更新了 ORM 模型定义

企业级团队（15+ 人）

企业级团队面临更复杂的治理需求：多代码仓库管理、权限控制、审计追踪和合规要求。PinableAgents 通过以下机制支持企业级场景：

多仓库配置

企业通常维护多个代码仓库，每个仓库可能有不同的技术栈和质量标准。PinableAgents 支持全局配置与仓库级配置的分层覆盖机制。

# 全局企业级配置（存放在配置中心或共享仓库中）
# ~/.pinable-agents/enterprise-config.json
{
  "enterprise": {
    "org_name": "Acme Corp",
    "policy_version": "2.1",
    "mandatory_gates": ["sparv", "security-scan"],
    "forbidden_skills": ["auto-deploy-prod"],
    "audit": {
      "enabled": true,
      "log_path": "/var/log/pinable-agents/audit.log",
      "retention_days": 90
    },
    "approved_backends": ["claude", "codex"],
    "max_token_budget_per_task": 500000
  }
}

治理策略

  • 审计追踪 - 记录每次工作流执行的详细信息，包括输入任务、使用的智能体、生成的代码变更和质量门控结果
  • 权限控制 - 限制特定工作流或技能的使用范围，例如只有高级工程师可以使用 auto-deploy 技能
  • 成本管控 - 设置每个任务的最大 token 预算，防止意外的高额 API 调用
  • 合规检查 - 确保生成的代码不包含开源许可证冲突或敏感数据泄露

渐进式采用策略

无论团队规模如何，都建议采用渐进式的引入方式，而非一步到位地部署所有功能。推荐的三阶段路径：

第一阶段：体验期（1-2 周）

安装 essentials 模块，让 1-2 名先行者在日常工作中使用基础的代码生成和审查功能。目标是验证工具的可用性和团队的接受度。

第二阶段：标准化期（3-4 周）

引入 do 工作流，建立团队共享配置，将 PinableAgents 集成到代码审查流程中。目标是形成标准化的使用规范。

第三阶段：深化期（5-8 周）

根据团队需求引入 bmad 或 omo 工作流，开发自定义技能和智能体，配置质量门控。目标是让 PinableAgents 成为团队工作流的核心组成部分。

渐进式采用的关键是在每个阶段结束时进行回顾，收集团队反馈并调整下一阶段的计划。强制推行往往适得其反，让团队自然地感受到工具的价值才是最佳策略。

常见反模式与规避方法

在团队采用 PinableAgents 的过程中，以下反模式需要特别警惕：

反模式 表现 规避方法
盲目信任 不审查智能体生成的代码就直接合并 始终要求人工审查，将智能体输出视为"草稿"而非"成品"
过度配置 花大量时间微调配置而非实际使用 使用默认配置开始，只在遇到实际问题时调整
技能膨胀 创建大量自定义技能导致预算超出 定期审查技能列表，删除使用率低的技能
工作流滥用 所有任务都使用最重量级的 bmad 工作流 根据任务复杂度选择合适的工作流
孤岛使用 团队成员各自使用不同的配置和工作流 将配置纳入版本控制，定期同步最佳实践
忽视反馈 不收集团队成员对工具的使用反馈 每个 Sprint 安排 15 分钟讨论工具使用体验

团队生产力度量

量化 PinableAgents 对团队生产力的影响有助于持续优化工具的使用。推荐追踪以下指标：

  • 任务完成时间 - 从需求分配到代码合并的平均时间。使用 PinableAgents 后，此指标通常下降 30-50%。
  • 代码审查轮次 - 从提交到通过审查的平均轮次。智能体预审查通常将轮次从 3-4 次降低到 1-2 次。
  • 缺陷密度 - 每千行代码的缺陷数量。质量门控的引入应使此指标持续下降。
  • 工作流成功率 - 工作流端到端成功完成的比例。低成功率可能意味着配置或任务描述需要优化。
# 生成团队生产力报告
pinable-agents metrics report --period 30d

# 输出示例：
# Team Productivity Report (Last 30 Days)
# ────────────────────────────────────────
# Tasks completed:          47
# Avg completion time:      2.3 hours (↓ 40% vs baseline)
# Code review rounds:       1.4 avg (↓ 55% vs baseline)
# Quality gate pass rate:   89%
# Workflow success rate:     92%

新成员入职清单

当新成员加入团队时，按照以下清单进行 PinableAgents 的入职引导：

  1. 安装 PinableAgents 桌面端和 CLI 工具（参考安装指南）
  2. 克隆项目仓库，确认 .pinable-agents/ 目录中的团队配置已自动加载
  3. 配置个人 AI 后端 API 密钥
  4. 运行 pinable-agents doctor 确认环境健康
  5. 阅读团队的工作流使用规范文档
  6. 在测试项目上独立完成一个 do 工作流练习
  7. 在正式项目上完成一个简单的 Bug 修复任务（有高级成员陪同）
  8. 参加团队的 PinableAgents 使用分享会，了解团队积累的最佳实践

新成员的入职质量直接影响他们对工具的长期使用态度。不要急于让新成员独立使用复杂工作流，给予充分的引导和练习时间才能建立正确的使用习惯。