claude-collaboration

Claude Code 协作最佳实践

本技能提供有关如何在团队环境中有效使用 Claude Code、通过技能管理共享知识，以及最大限度发挥 AI 辅助开发价值的指导。

核心原则

1. 技能是不断完善的文档——随着学习不断演进
2. 明确记录知识——Claude 不会自动更新技能
3. 所有技能都存放在 $CLAUDE_METADATA 中——项目中不放置本地技能或命令
4. 在团队中共享知识——集中式仓库确保一致性
5. 对技能进行版本控制——跟踪变更和改进
6. 有选择地更新——并非所有新知识都需要记录

重要：不创建本地技能或命令

所有技能和命令都必须放在 $CLAUDE_METADATA 仓库中，绝不能放在各个项目目录里。

切勿这样做：

# Creating local skill in project
echo "---" > .claude/skills/my-local-skill/SKILL.md

始终这样做：

# Create skill in central repo
mkdir -p $CLAUDE_METADATA/skills/project-name
echo "---" > $CLAUDE_METADATA/skills/project-name/SKILL.md

# Then symlink to project
ln -s $CLAUDE_METADATA/skills/project-name .claude/skills/project-name

必须集中管理的原因：

• 版本控制：所有技能都在同一个 git 仓库中进行跟踪
• 团队共享：所有人使用相同的知识
• 一致性：不同项目之间不会出现差异
• 维护：更新一次，即可应用到所有地方
• 发现：团队可以查看所有可用技能

即使是特定于项目的技能，也要放在中央仓库的 $CLAUDE_METADATA/skills/project-name/ 下。

---

了解技能的工作方式

会话期间会发生什么

会话开始时：

• Claude 会读取你所在目录中的所有 .claude/skills/ 文件
• 技能为会话提供上下文和指导原则
• 技能中的知识会“加载”到 Claude 的工作上下文中

会话期间：

• Claude 会从对话中学习（临时的上下文学习）
• 发现的解决方案仅适用于当前对话
• 除非你明确更新，否则技能不会改变

会话结束时：

• 所有临时学习内容都会丢失
• 技能保持会话开始时的原样
• 下次会话会重新开始，并再次读取技能

这意味着什么

• 技能会跨会话保留——它们是磁盘上的文件
• 会话中的学习不会保留——它们只存在于对话上下文中
• 你必须明确更新技能——Claude 不会自动更新

---

何时更新技能

以下情况务必更新技能：

1. 已知解决方案的问题反复出现

   • “我们总是遇到这个错误，解决方法如下”
   • 添加到故障排除部分

2. 发现了新的最佳实践

   • “使用 --quiet 可节省 85% 的令牌，默认使用它”
   • 添加到优化指南

3. 需要标准化的常见工作流

   • “我们的团队总是在 Y 之前执行 X”
   • 添加到标准流程

4. 有效的配置模式

   • “这种 cron 作业设置最适合我们的 HPC”
   • 作为推荐配置添加

5. 重要的架构决策

   • “我们决定使用符号链接来设置全局技能，因为……”
   • 记录原因，以供日后参考

以下情况不要更新技能：

1. 一次性问题——仅适用于某次运行或特定环境
2. 实验性方法——等验证有效后再记录
3. 用户个人偏好——除非应作为团队默认设置
4. 显而易见的信息——其他地方已有完善文档
5. 临时变通方案——不值得将其永久化

示例：何时更新

场景 1：发现新的错误模式

Session: "WF8 fails when Hi-C files are missing R2 reads"
Action: ADD to troubleshooting - this will happen again
Rationale: Common issue with known solution

场景 2：一次性的配置问题

Session: "My personal laptop has Python 3.7, need 3.8"
Action: DON'T ADD to skill - personal environment issue
Rationale: Not relevant to others, not a recurring pattern

场景 3：发现令牌优化方法

Session: "Using --quiet mode saves 15K to 2K tokens!"
Action: ADD to token efficiency skill
Rationale: Valuable for entire team, significant impact

---

如何更新技能

方法 1：明确提出请求（推荐）

User: "We just solved the issue with workflow timeouts in HPC environments.
       Add this to the VGP skill under troubleshooting."

Claude: [Reads current skill, adds new troubleshooting entry, saves file]

方法 2：让 Claude 提出更新建议

User: "Based on our work today, what should we add to the VGP skill?"
Claude: [Reviews conversation, suggests additions]
User: "Yes, add those three things."
Claude: [Updates skill file]

方法 3：会话结束时总结

User: "Summarize today's learnings and update the relevant skills."
Claude: [Creates summary, updates multiple skills if needed]

方法 4：定期审查

User: "We've been working on VGP for a month.
       Review our conversation history and suggest skill improvements."
Claude: [Analyzes patterns, suggests updates]

---

技能组织模式

模式 1：特定于项目的技能（存放在中央仓库中）

适用场景： 特定于项目的知识（VGP 工作流、Galaxy API）

位置： $CLAUDE_METADATA/skills/project-name/（不要放在项目目录中）

$CLAUDE_METADATA/
└── skills/
    ├── my-project/              # Project-specific skill
    │   └── SKILL.md
    └── another-project/
        └── SKILL.md

my-project/
└── .claude/
    └── skills/
        └── my-project -> $CLAUDE_METADATA/skills/my-project  # Symlink only!

模式 2：通用技能（跨项目）

适用场景： 通用开发实践、与工具无关的优化、团队范围的标准

位置： $CLAUDE_METADATA/skills/

模式 3：将技能符号链接到项目

这是标准模式——所有项目都使用符号链接，无一例外。

# In each project
cd /path/to/project
mkdir -p .claude/skills .claude/commands

# Symlink skills from central repo
ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency
ln -s $CLAUDE_METADATA/skills/my-project .claude/skills/my-project

# Symlink commands from central repo
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

关键规则： 项目中只能包含符号链接，绝不能包含实际的技能／命令文件。

模式 4：附带支持文档的技能

skills/skill-name/
├── SKILL.md              # Core concepts and quick reference
├── reference.md          # Detailed technical documentation
├── troubleshooting.md    # Common issues and solutions
├── examples/             # Code examples
└── templates/            # Template files

适用场景：

• SKILL.md 越来越长（超过 500 行）
• 有详细的参考资料可用
• 信息分为多个类别（指南、故障排除、示例）

最佳实践：

• 将 SKILL.md 控制在 500 行以内
• 将详细指南移至支持文件
• 在 SKILL.md 末尾引用支持文件
• 使用描述性文件名（例如 troubleshooting.md，而不是 tips.md）

---

快速参考

日常工作流

1. Start session -> Claude reads skills
2. Work on task -> Learn new patterns
3. End session -> "What should we add to skills?"
4. Claude suggests -> You approve/modify
5. Git commit -> Share with team

每周维护

1. Review week's commits
2. Identify patterns across sessions
3. Consolidate related updates
4. Remove outdated info
5. Share changelog with team

每月审查

1. Audit all skills for conflicts
2. Measure token savings
3. Collect team feedback
4. Major refactoring if needed
5. Update skill documentation

---

总结

核心原则：

1. 技能是长期存在的，会话是临时的
2. 明确更新技能——Claude 不会自动更新
3. 所有技能都放在 $CLAUDE_METADATA 中——绝不创建本地技能或命令
4. 使用 git 在中央仓库中对技能进行版本控制
5. 在团队中共享技能——集中管理可确保一致性
6. 定期审查，让技能持续发挥价值

关键架构规则：

• 绝不要直接在项目目录中创建技能或命令
• 始终在 $CLAUDE_METADATA 中创建，并符号链接到项目

即使是项目专属的技能，也必须存放在中央仓库中。这样可以确保：

• 单一事实来源——没有重复内容，也不会出现分歧
• 版本控制——所有技能都在同一个 git 仓库中跟踪
• 团队共享——每个人都能发现并使用所有技能
• 易于维护——只需更新一次，即可在各处生效

请记住： Claude 是强大的助手，但技能能让这种能力变得一致、可共享且持久。集中式架构可确保团队知识井然有序、易于发现和维护。投入精力完善技能，就能让整个团队长期受益。

---

支持文档

此技能在同一目录中包含详细的参考文档：

• centralized-repository.md - 中央技能仓库的设置、迁移模式、团队工作流和目录结构示例
• version-control-and-sharing.md - 技能的 Git 设置、团队协作工作流，以及四种技能共享方式（Git 仓库、网络驱动器、基于复制的方式、ZIP 压缩包）
• maintenance-and-effectiveness.md - 技能维护最佳实践、效果评估、跟踪指标，以及常见问题与解决方案
• advanced-patterns.md - 分层／条件／基于角色的技能模式，以及会话中断文档（恢复文档模板）

这些文件提供了深入的技术细节，可补充上述核心概念。