Claude代码指导框架

持续的指导。执行的标准。

这是什么？

这个项目是 综合指导框架 Claude Code保留了您的开发风格、标准和文档指导。该框架没有反复向人工智能助手说明你的偏好，而是：

获取您的指导 结构化文档
执行您的标准 通过MCP代理自动
保留您的风格 在所有开发会话中
扩展您的专业知识 通过GPT-5.2授权顾问

核心理念： 持续的指导。执行的标准。

什么是转向？

转向是在版本控制文档中捕获您的开发指导，然后在每次代码更改期间让AI代理自动执行它的做法。

传统方法：

手动审查每个拉取请求
在代码审查中反复解释相同的标准
希望开发人员记住您的偏好
随着上下文的丢失，标准会随着时间的推移而漂移

转向方法：

记录您的标准 docs/
GPT-5.2代理自动读取并执行它们
标准随着git的历史而发展
发现新模式→ 添加到文档→ 各地强制执行

主要区别： 你的专业知识成为基础设施，而不是部落知识。

起源

该框架源于 真正的Python项目 （0到200000行代码），通过使用Claude code的迭代指导来捕获和完善开发原则。项目细节已被剥离，但 软件开发基本原则 保留：

语言不可知原则 -可测试性、类型安全、清晰的抽象、系统调试
Python特定实践 -现代类型提示、Pydantic模式、ABC模式、基于继承的伪造
久经考验的模式 -每一条规则 docs/ 解决了真正的问题或防止了真正的错误

文档的结构如下 将普遍原则与语言特定规则分开，使该框架易于适应其他语言（TypeScript、Go、Rust等），同时保留核心开发理念。

快速入门（5分钟）

此存储库是 模板/转向包 克劳德代码。这是你得到的：

预配置的MCP代理 -三名GPT-5.2专业代理随时准备执行您的标准
全面的文件 -5个详细的指南，涵盖代码风格、测试、架构、故障排除和基础设施
工作流程自动化 -Claude Code在关键开发步骤自动咨询代理
自我提升 -文档会随着发现的每一个新模式而更新

今天可以运行的内容：

阅读文档 docs/ 了解编码标准
查看中的MCP代理配置 prompts/
启动一个Claude会话，并要求它计划一个功能——它将自动咨询代理
将其克隆为您的项目模板，并根据您的喜好自定义标准

您将添加的内容：

src/ -您的应用程序代码（遵循docs/code-style.md）
tests/ -您的测试套件（遵循docs/test-style.md）

适应其他语言：

文档分为 基本原则 （语言不可知论）和 Python特定规则
保持基本原则部分的完整性
询问克劳德代码： *“将Python特定的部分翻译为TypeScript/Go/Rust”*
审阅克劳德的翻译，并根据需要进行改进
更新MCP代理提示以参考您的语言标准

TypeScript的示例工作流程：

User: "Read docs/code-style.md and translate all Python-specific sections to TypeScript. Keep the fundamental principles unchanged."

Claude: [Produces TypeScript-specific type system rules, testing patterns, etc.]

User: "Review and enhance the TypeScript translation with best practices."

Claude: [Refines the translation, adds TypeScript idioms]

运作原理

1.文件作为指导机制

您的所有开发偏好都记录在：

docs/code-style.md -您的编码标准（类型安全、模式、架构）
docs/test-style.md -你的测试理念（没有模拟、基于继承的伪造、90%的覆盖率）
docs/troubleshooting.md -您的调试方法和常见解决方案
docs/architecture.md -您的系统架构和设计模式
docs/infrastructure-style.md -您的基础设施标准（Terraform/IaC、CI/CD、部署）
CLAUDE.md -您对Claude Code的工作流程和流程指导

2.通过MCP代理自动执行

三个GPT-5.2专业代理自动执行您的标准：

代理	MCP服务器名称	时间	目的
GPT架构师	`gpt5-architect`	步骤0，步骤T-1	根据您的架构原则验证设计决策
GPT审阅者	`gpt5-reviewer`	步骤T、T+1、L-1	确保代码符合您的标准
GPT故障排除程序	`gpt5-troubleshooter`	调试时	应用您的系统故障排除方法

注：显示名称（GPT架构师）和MCP服务器名称(gpt5-architect)指代相同的代理人。

这些代理会阅读您的文档，并在每个功能、重构或bug修复中强制执行。

3.自我完善的文件

每次开发会话都会更新文档（步骤L）：

发现新模式→ 添加到code-style.md
遇到的Bug→ 添加到疑难解答.md
架构决策→ 在architecture.md中捕获

结果： 你的指导会随着时间的推移而变得更强，永远不会重复，永远可用。

先决条件

所需工具

克劳德代码 -用于软件工程的AI驱动CLI

- 产品页面：https://claude.com/code - 需要Claude Pro或API访问权限

Codex CLI -GPT-5.2代理的MCP服务器运行时

- github：https://github.com/openai/codex - 版本：0.72.0+

Node.js -对于Context7 MCP代理

- 需要运行npx命令 - 版本：18+推荐

python - 3.12+

- 用于项目代码（当您开始编写实际的应用程序代码时）

Git -用于版本控制和工作台工作流

上下文7 API密钥 -用于图书馆文档查找

- 注册地址：https://context7.ai - 免费套餐可用

安装

第一步：安装Claude代码

# macOS (via Homebrew)
brew install --cask claude-code

# Or download from: https://claude.com/code

验证安装：

claude --version

步骤2：安装Codex CLI

# macOS (via Homebrew)
brew install --cask codex

# Or download from: https://github.com/openai/codex

验证安装：

codex --version  # Should show v0.72.0+

使用OpenAI API密钥配置Codex（用于GPT-5.2访问）：

# Set up authentication
codex login

# Or set environment variable
export OPENAI_API_KEY="your-api-key"

步骤3：克隆此存储库

git clone https://github.com/your-username/claudecode-steering-blog.git
cd claudecode-steering-blog

注：替换 your-username 如果你已经分叉了这个仓库，请使用你的实际GitHub用户名。

步骤4：配置Context7 API密钥

Context7在编码时提供库文档查找

1.获取API密钥： 访问https://context7.ai并注册一个免费的API密钥

2.设置环境变量：

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export CONTEXT7_API_KEY="your-api-key-here"

# Reload shell
source ~/.bashrc  # or ~/.zshrc

3.验证：

echo $CONTEXT7_API_KEY  # Should display your key

Context7已在中配置 .mcp.json 并且一旦设置了环境变量就可用。

步骤5：验证MCP代理

测试所有MCP代理是否已配置：

# From project root
claude mcp list

您应该看到：

✅ gpt5架构师-已连接
✅ gpt5审阅者-已连接
✅ gpt5故障排除程序-已连接

注： claude mcp list 仅检查连接。要验证身份验证和完整功能，请启动Claude会话，代理将在首次调用时进行测试。

项目结构

claudecode-steering-blog/
├── docs/                      # Your steering documentation
│   ├── code-style.md         # Coding standards
│   ├── test-style.md         # Testing standards
│   ├── troubleshooting.md    # Debug procedures
│   ├── architecture.md       # System architecture
│   └── infrastructure-style.md # Infrastructure standards (Terraform, CI/CD)
├── prompts/                   # MCP agent system prompts
│   ├── architect.txt         # Architect agent configuration
│   ├── reviewer.txt          # Reviewer agent configuration
│   └── troubleshooter.txt    # Troubleshooter agent configuration
├── scripts/                   # MCP agent launchers
│   └── gpt5-agent.sh         # Unified script for all three GPT-5 agents
├── .mcp.json                  # MCP server configuration
├── CLAUDE.md                  # Claude Code workflow guidance
├── AGENTS.md                  # Agent usage notes
└── README.md                  # This file

注： src/ 和 tests/ 目录将在您开始编写代码时创建。

用法

启动开发会话

# Use git worktrees for feature isolation (recommended)
git worktree add ../myproject-feature -b feature-name
cd ../myproject-feature

# Start Claude Code
claude

克劳德将：

阅读 CLAUDE.md 用于工作流指导
规划功能时咨询GPT架构师
测试前后咨询GPT审核员
自动执行您的标准
用新模式更新文档（步骤L）

Git工作树工作流

始终使用git工作树进行功能开发 -这在CLAUDE.md中强制执行

为什么选择工作树：

将每个功能隔离在自己的目录中
立即在功能之间切换（无需隐藏）
并行处理多个功能
保持主干清洁

设置新功能：

# From your main project directory
cd /path/to/claudecode-steering-blog

# Create worktree for new feature
git worktree add ../claudecode-steering-blog-feature-name -b feature-name

# Move into the worktree
cd ../claudecode-steering-blog-feature-name

# Start Claude Code
claude

列出您的工作树：

git worktree list

完成后拆下工作台：

git worktree remove ../claudecode-steering-blog-feature-name

计划模式：编辑前始终计划

关键：对所有非琐碎的更改使用计划模式

当克劳德建议更改时，务必先使用计划模式：

触发计划模式 -克劳德将进入复杂任务的计划模式
审查计划 -在编写任何代码之前检查拟议的更改
提供反馈 -提出问题，要求改变方法
批准或拒绝 -只有在满意时才接受计划
执行 -克劳德在计划批准后实施

优点：

在编写代码之前查看方法
及早发现设计问题
不要在错误的方向上浪费精力
对变化有清晰的认识

在克劳德代码中：

复杂任务会自动触发计划模式
您始终可以要求先查看计划
计划包括文件更改、新文件、测试方法
在规划过程中咨询MCP代理人（建筑师、审查员）

上下文7：图书馆文档查找

Context7在编码时提供对库文档的即时访问

*注意：Context7 API密钥应该已经从安装的步骤4中配置。如果没有，请参阅该部分。*

使用上下文7

在开发过程中，Claude可以：

自动查找库文档
获取最新API参考资料
查找使用示例
检查兼容性

例子：

User: "Use httpx for API calls"

Claude (via Context7):
  ├─ Looks up httpx documentation
  ├─ Finds async client examples
  ├─ Checks latest version compatibility
  └─ Implements with best practices

手动查找：

User: "What's the context7 documentation for Pydantic?"
Claude: [Uses context7 MCP agent to fetch Pydantic docs]

支持的库： 最流行的Python、JavaScript和其他语言

典型开发流程

User: "Add user authentication feature"

Claude:
  ├─ Reads docs/code-style.md, docs/architecture.md
  ├─ Creates implementation plan
  ├─ Step 0: Consults GPT-Architect (validates design)
  ├─ Implements feature following your standards
  │   ├─ NewType for UserIds
  │   ├─ Pydantic schemas for data
  │   ├─ ABC (not Protocol) for interfaces
  │   ├─ Dependencies passed as parameters (testable)
  │   └─ Context managers for resources
  ├─ Step T: Consults GPT-Reviewer (pre-test review)
  ├─ Writes tests (inheritance-based fakes, no mocks)
  ├─ Step T+1: Consults GPT-Reviewer (post-test review)
  ├─ Step L-1: Final review with GPT-Reviewer
  └─ Step L: Updates documentation with new patterns

MCP代理在行动

GPT架构师 （步骤0，T-1）：

Reviewing your plan for user authentication...

✅ Approvals:
- Business logic testable (dependencies passed as parameters)
- NewType(UserId) defined in src/utils/types.py
- Pydantic schemas for User, Credentials
- Using ABC, not Protocol ✓

⚠️ Concerns:
- src/auth/service.py:45 - Thin wrapper detected
  Recommendation: Expose auth.sessions.create() directly

💡 Recommendations:
- Consider ABC for shared session logic
- Check if auth library already exists (httpx-auth, authlib)?

GPT审阅者 （步骤T、T+1、L-1）：

Reviewing code changes...

✅ Approvals:
- Type safety: All IDs use NewType ✓
- Modern syntax: Using list[str] not List[str] ✓

🐛 Bugs Found:
- src/auth/service.py:67 - Unhandled None return
  Fix: Add None check before accessing result.user_id

⚠️ Standards Violations:
- tests/unit/auth/test_service.py:12 - Using unittest.mock
  Fix: Replace with inheritance-based FakeAuthService

GPT故障排除程序 （调试时）：

🔍 Hypothesis:
Database connection not properly closed in error path

✅ Verification Plan:
1. Add logging at auth/service.py:45 (before DB call)
2. Add logging at auth/service.py:52 (after DB call)
3. Run: grep -r "Database(" src/ (find similar patterns)

⚡ Speed Up Debugging:
pytest -k "test_auth_failure" -v

文件标准

您的指导信息记录在：

docs/code-style.md -强制执行：

零 Any 业务逻辑中的类型
所有域ID的NewType
所有数据契约的Pydantic模式
可测试性编排器模式
ABC用于50%以上的代码重用
内部代码中没有协议
没有薄包装

docs/test-style.md -强制执行：

不 unittest.mock 或 monkeypatch
仅基于继承的假货
业务逻辑覆盖率目标为90%
Bug修复必须包括测试用例

docs/故障排除.md -指南：

8系统故障排除原则
在修复之前搜索类似的错误
尽量减少复制时间
常见错误模式及其解决方案

为您的项目进行自定义

更新您的标准

编辑文档文件以符合您的偏好：

# Edit coding standards
vim docs/code-style.md

# Edit testing standards
vim docs/test-style.md

# Edit troubleshooting approaches
vim docs/troubleshooting.md

MCP代理将自动执行您更新的标准。

自定义MCP代理

编辑代理系统提示：

# Customize architect behavior
vim prompts/architect.txt

# Customize reviewer behavior
vim prompts/reviewer.txt

# Customize troubleshooter behavior
vim prompts/troubleshooter.txt

更改立即生效（代理在每次调用时重新加载提示）。

安全考虑

⚠️ 重要安全注意事项：

.mcp.json 执行本地脚本 -配置文件运行bash脚本(scripts/gpt5-agent.sh)当MCP代理被调用时。运行前务必查看此脚本。

供应链风险 -如果使用 npx -y 对于Context7或其他MCP代理，软件包会自动下载并执行。考虑：

- 将特定版本固定在 .mcp.json - 首次使用前检查包装内容 - 使用本地安装而不是 npx -y

API密钥 -将OpenAI和Context7 API键存储在环境变量中，永远不要将它们提交给git。

首次批准 -Claude Code在首次访问MCP服务器时可能会提示批准。这是预期的行为——在批准之前审查正在执行的内容。

建议：

查看中的所有脚本 scripts/ 目录
检查 .mcp.json 使用前配置
保持Codex和Claude Code的更新
使用git跟踪代理配置的更改

主要特点

✅ 转向优先

切勿重复指导 -文件一次，永远执行
版本控制标准 -你的指导随着git而发展
自动执行 -GPT-5.2代理应用您的规则

✅ 类型安全第一

所有域ID的NewType
所有数据的Pydantic模式
零 Any 业务逻辑中的类型
现代Python 3.10+语法

✅ 设计可测试性

编排器模式（可测试，无依赖关系）
基于继承的伪造（无模拟）
90%覆盖率目标
Bug修复需要测试

✅ 系统调试

8故障排除原则
搜索相似模式
最小化迭代时间
GPT-5.2调试协助

✅ Git工作树工作流

功能隔离
轻松切换上下文
无需隐藏

MCP代理详细信息

建筑

Claude Code (You)
    ↓
CLAUDE.md (Workflow guidance)
    ↓
┌──────────────┬──────────────┬──────────────────┬─────────────┐
│              │              │                  │             │
│GPT-Architect │ GPT-Reviewer │GPT-Troubleshooter│  Context7   │
│(Step 0, T-1) │(T, T+1, L-1) │  (When debugging)│(Doc lookup) │
│              │              │                  │             │
└──────┬───────┴──────┬───────┴────────┬─────────┴──────┬──────┘
       │              │                │                │
       ↓              ↓                ↓                ↓
  code-style.md  test-style.md  troubleshooting.md  Library Docs

代理能力

能力	GPT架构师	GPT审阅者	GPT疑难解答	Context7
MCP服务器名称	`gpt5-architect`	`gpt5-reviewer`	`gpt5-troubleshooter`	`context7`
阅读文档	✅	✅	✅	-
读取代码	✅	✅	✅	-
搜索代码库	✅	✅	✅	-
库文档	-	-			✅
API引用查找	-	-			✅
用法示例	-	-			✅
高推理预算	✅	✅	✅	-
响应时间	5-10min	5-10min	5-10min/5-10min	\<1秒
型号	GPT-5.2	GPT-5.2	GPT-2.2	Context7 API
推理努力	高	高	不适用

贡献

这是一个个人指导框架。分叉并根据您的需求进行定制！

分享改进：

分叉存储库
创建要素分支
使用您的模式更新文档
提交拉取请求

许可证

Apache 2.0-请参阅许可证文件

致谢

克劳德代码 通过Anthropic-AI驱动的开发CLI
法典由OpenAI-MCP服务器运行时为GPT-5.2代理提供动力
GPT-5.2 OpenAI-为三个专业MCP代理（架构师、审阅者、故障排除者）提供支持
背景7 -库文档查找和API参考

______________________________________________________________________

已知问题

Context Rot。当claude进行压缩时，它会忘记claude.md中的大部分指令。这会导致忘记调用mcp服务器、破坏样式指南等。尽可能经常地解决/清除问题，不要将两个不同的任务安排在同一个上下文中。把任务分配好。

claudecode steering

快速接入

详细介绍