mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-10 11:23:32 +08:00
Revert "feat(ecc): prune plugin 43→12 items, promote 7 rules to .claude/rules/ (#245)"
This reverts commit 1bd68ff534.
This commit is contained in:
80
docs/zh-CN/rules/README.md
Normal file
80
docs/zh-CN/rules/README.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# 规则
|
||||
|
||||
## 结构
|
||||
|
||||
规则被组织为一个**通用**层加上**语言特定**的目录:
|
||||
|
||||
```
|
||||
rules/
|
||||
├── common/ # Language-agnostic principles (always install)
|
||||
│ ├── coding-style.md
|
||||
│ ├── git-workflow.md
|
||||
│ ├── testing.md
|
||||
│ ├── performance.md
|
||||
│ ├── patterns.md
|
||||
│ ├── hooks.md
|
||||
│ ├── agents.md
|
||||
│ └── security.md
|
||||
├── typescript/ # TypeScript/JavaScript specific
|
||||
├── python/ # Python specific
|
||||
└── golang/ # Go specific
|
||||
```
|
||||
|
||||
* **common/** 包含通用原则 —— 没有语言特定的代码示例。
|
||||
* **语言目录** 通过框架特定的模式、工具和代码示例来扩展通用规则。每个文件都引用其对应的通用文件。
|
||||
|
||||
## 安装
|
||||
|
||||
### 选项 1:安装脚本(推荐)
|
||||
|
||||
```bash
|
||||
# Install common + one or more language-specific rule sets
|
||||
./install.sh typescript
|
||||
./install.sh python
|
||||
./install.sh golang
|
||||
|
||||
# Install multiple languages at once
|
||||
./install.sh typescript python
|
||||
```
|
||||
|
||||
### 选项 2:手动安装
|
||||
|
||||
> **重要提示:** 复制整个目录 —— 不要使用 `/*` 将其扁平化。
|
||||
> 通用目录和语言特定目录包含同名的文件。
|
||||
> 将它们扁平化到一个目录会导致语言特定的文件覆盖通用规则,并破坏语言特定文件使用的相对 `../common/` 引用。
|
||||
|
||||
```bash
|
||||
# Install common rules (required for all projects)
|
||||
cp -r rules/common ~/.claude/rules/common
|
||||
|
||||
# Install language-specific rules based on your project's tech stack
|
||||
cp -r rules/typescript ~/.claude/rules/typescript
|
||||
cp -r rules/python ~/.claude/rules/python
|
||||
cp -r rules/golang ~/.claude/rules/golang
|
||||
|
||||
# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
|
||||
```
|
||||
|
||||
## 规则与技能
|
||||
|
||||
* **规则** 定义广泛适用的标准、约定和检查清单(例如,“80% 的测试覆盖率”、“没有硬编码的密钥”)。
|
||||
* **技能**(`skills/` 目录)为特定任务提供深入、可操作的参考材料(例如,`python-patterns`,`golang-testing`)。
|
||||
|
||||
语言特定的规则文件会在适当的地方引用相关的技能。规则告诉你*要做什么*;技能告诉你*如何去做*。
|
||||
|
||||
## 添加新语言
|
||||
|
||||
要添加对新语言的支持(例如,`rust/`):
|
||||
|
||||
1. 创建一个 `rules/rust/` 目录
|
||||
2. 添加扩展通用规则的文件:
|
||||
* `coding-style.md` —— 格式化工具、习惯用法、错误处理模式
|
||||
* `testing.md` —— 测试框架、覆盖率工具、测试组织
|
||||
* `patterns.md` —— 语言特定的设计模式
|
||||
* `hooks.md` —— 用于格式化工具、代码检查器、类型检查器的 PostToolUse 钩子
|
||||
* `security.md` —— 密钥管理、安全扫描工具
|
||||
3. 每个文件应以以下内容开头:
|
||||
```
|
||||
> 此文件通过 <语言> 特定内容扩展了 [common/xxx.md](../common/xxx.md)。
|
||||
```
|
||||
4. 如果现有技能可用,则引用它们,或者在 `skills/` 下创建新的技能。
|
||||
52
docs/zh-CN/rules/common/agents.md
Normal file
52
docs/zh-CN/rules/common/agents.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# 智能体编排
|
||||
|
||||
## 可用智能体
|
||||
|
||||
位于 `~/.claude/agents/` 中:
|
||||
|
||||
| 智能体 | 用途 | 使用时机 |
|
||||
|-------|---------|-------------|
|
||||
| planner | 实现规划 | 复杂功能、重构 |
|
||||
| architect | 系统设计 | 架构决策 |
|
||||
| tdd-guide | 测试驱动开发 | 新功能、错误修复 |
|
||||
| code-reviewer | 代码审查 | 编写代码后 |
|
||||
| security-reviewer | 安全分析 | 提交前 |
|
||||
| build-error-resolver | 修复构建错误 | 构建失败时 |
|
||||
| e2e-runner | 端到端测试 | 关键用户流程 |
|
||||
| refactor-cleaner | 清理死代码 | 代码维护 |
|
||||
| doc-updater | 文档 | 更新文档时 |
|
||||
|
||||
## 即时智能体使用
|
||||
|
||||
无需用户提示:
|
||||
|
||||
1. 复杂的功能请求 - 使用 **planner** 智能体
|
||||
2. 刚编写/修改的代码 - 使用 **code-reviewer** 智能体
|
||||
3. 错误修复或新功能 - 使用 **tdd-guide** 智能体
|
||||
4. 架构决策 - 使用 **architect** 智能体
|
||||
|
||||
## 并行任务执行
|
||||
|
||||
对于独立操作,**始终**使用并行任务执行:
|
||||
|
||||
```markdown
|
||||
# 良好:并行执行
|
||||
同时启动 3 个智能体:
|
||||
1. 智能体 1:认证模块的安全分析
|
||||
2. 智能体 2:缓存系统的性能审查
|
||||
3. 智能体 3:工具类的类型检查
|
||||
|
||||
# 不良:不必要的顺序执行
|
||||
先智能体 1,然后智能体 2,最后智能体 3
|
||||
|
||||
```
|
||||
|
||||
## 多视角分析
|
||||
|
||||
对于复杂问题,使用拆分角色的子智能体:
|
||||
|
||||
* 事实审查员
|
||||
* 高级工程师
|
||||
* 安全专家
|
||||
* 一致性审查员
|
||||
* 冗余检查器
|
||||
52
docs/zh-CN/rules/common/coding-style.md
Normal file
52
docs/zh-CN/rules/common/coding-style.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# 编码风格
|
||||
|
||||
## 不可变性(关键)
|
||||
|
||||
始终创建新对象,绝不改变现有对象:
|
||||
|
||||
```
|
||||
// Pseudocode
|
||||
WRONG: modify(original, field, value) → changes original in-place
|
||||
CORRECT: update(original, field, value) → returns new copy with change
|
||||
```
|
||||
|
||||
理由:不可变数据可以防止隐藏的副作用,使调试更容易,并支持安全的并发。
|
||||
|
||||
## 文件组织
|
||||
|
||||
多个小文件 > 少数大文件:
|
||||
|
||||
* 高内聚,低耦合
|
||||
* 通常 200-400 行,最多 800 行
|
||||
* 从大型模块中提取实用工具
|
||||
* 按功能/领域组织,而不是按类型组织
|
||||
|
||||
## 错误处理
|
||||
|
||||
始终全面处理错误:
|
||||
|
||||
* 在每个层级明确处理错误
|
||||
* 在面向用户的代码中提供用户友好的错误消息
|
||||
* 在服务器端记录详细的错误上下文
|
||||
* 绝不默默地忽略错误
|
||||
|
||||
## 输入验证
|
||||
|
||||
始终在系统边界处进行验证:
|
||||
|
||||
* 在处理前验证所有用户输入
|
||||
* 在可用时使用基于模式的验证
|
||||
* 快速失败并提供清晰的错误消息
|
||||
* 绝不信任外部数据(API 响应、用户输入、文件内容)
|
||||
|
||||
## 代码质量检查清单
|
||||
|
||||
在标记工作完成之前:
|
||||
|
||||
* \[ ] 代码可读且命名良好
|
||||
* \[ ] 函数短小(<50 行)
|
||||
* \[ ] 文件专注(<800 行)
|
||||
* \[ ] 没有深度嵌套(>4 层)
|
||||
* \[ ] 正确的错误处理
|
||||
* \[ ] 没有硬编码的值(使用常量或配置)
|
||||
* \[ ] 没有突变(使用不可变模式)
|
||||
46
docs/zh-CN/rules/common/git-workflow.md
Normal file
46
docs/zh-CN/rules/common/git-workflow.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Git 工作流程
|
||||
|
||||
## 提交信息格式
|
||||
|
||||
```
|
||||
<type>: <description>
|
||||
|
||||
<optional body>
|
||||
```
|
||||
|
||||
类型:feat, fix, refactor, docs, test, chore, perf, ci
|
||||
|
||||
注意:通过 ~/.claude/settings.json 全局禁用了归因。
|
||||
|
||||
## 拉取请求工作流程
|
||||
|
||||
创建 PR 时:
|
||||
|
||||
1. 分析完整的提交历史(不仅仅是最近一次提交)
|
||||
2. 使用 `git diff [base-branch]...HEAD` 查看所有更改
|
||||
3. 起草全面的 PR 摘要
|
||||
4. 包含带有 TODO 的测试计划
|
||||
5. 如果是新分支,使用 `-u` 标志推送
|
||||
|
||||
## 功能实现工作流程
|
||||
|
||||
1. **先做计划**
|
||||
* 使用 **planner** 代理创建实施计划
|
||||
* 识别依赖项和风险
|
||||
* 分解为多个阶段
|
||||
|
||||
2. **TDD 方法**
|
||||
* 使用 **tdd-guide** 代理
|
||||
* 先写测试(RED)
|
||||
* 实现代码以通过测试(GREEN)
|
||||
* 重构(IMPROVE)
|
||||
* 验证 80%+ 的覆盖率
|
||||
|
||||
3. **代码审查**
|
||||
* 编写代码后立即使用 **code-reviewer** 代理
|
||||
* 解决 CRITICAL 和 HIGH 级别的问题
|
||||
* 尽可能修复 MEDIUM 级别的问题
|
||||
|
||||
4. **提交与推送**
|
||||
* 详细的提交信息
|
||||
* 遵循约定式提交格式
|
||||
33
docs/zh-CN/rules/common/hooks.md
Normal file
33
docs/zh-CN/rules/common/hooks.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Hooks 系统
|
||||
|
||||
## Hook 类型
|
||||
|
||||
* **PreToolUse**:工具执行前(验证、参数修改)
|
||||
* **PostToolUse**:工具执行后(自动格式化、检查)
|
||||
* **Stop**:会话结束时(最终验证)
|
||||
|
||||
## 自动接受权限
|
||||
|
||||
谨慎使用:
|
||||
|
||||
* 为受信任、定义明确的计划启用
|
||||
* 为探索性工作禁用
|
||||
* 切勿使用 dangerously-skip-permissions 标志
|
||||
* 改为在 `~/.claude.json` 中配置 `allowedTools`
|
||||
|
||||
## TodoWrite 最佳实践
|
||||
|
||||
使用 TodoWrite 工具来:
|
||||
|
||||
* 跟踪多步骤任务的进度
|
||||
* 验证对指令的理解
|
||||
* 实现实时指导
|
||||
* 展示详细的实现步骤
|
||||
|
||||
待办事项列表可揭示:
|
||||
|
||||
* 步骤顺序错误
|
||||
* 缺失的项目
|
||||
* 额外不必要的项目
|
||||
* 粒度错误
|
||||
* 对需求的理解有误
|
||||
34
docs/zh-CN/rules/common/patterns.md
Normal file
34
docs/zh-CN/rules/common/patterns.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# 常见模式
|
||||
|
||||
## 骨架项目
|
||||
|
||||
当实现新功能时:
|
||||
|
||||
1. 搜索经过实战检验的骨架项目
|
||||
2. 使用并行代理评估选项:
|
||||
* 安全性评估
|
||||
* 可扩展性分析
|
||||
* 相关性评分
|
||||
* 实施规划
|
||||
3. 克隆最佳匹配作为基础
|
||||
4. 在已验证的结构内迭代
|
||||
|
||||
## 设计模式
|
||||
|
||||
### 仓库模式
|
||||
|
||||
将数据访问封装在一个一致的接口之后:
|
||||
|
||||
* 定义标准操作:findAll, findById, create, update, delete
|
||||
* 具体实现处理存储细节(数据库、API、文件等)
|
||||
* 业务逻辑依赖于抽象接口,而非存储机制
|
||||
* 便于轻松切换数据源,并使用模拟对象简化测试
|
||||
|
||||
### API 响应格式
|
||||
|
||||
对所有 API 响应使用一致的信封格式:
|
||||
|
||||
* 包含一个成功/状态指示器
|
||||
* 包含数据载荷(出错时可为空)
|
||||
* 包含一个错误消息字段(成功时可为空)
|
||||
* 为分页响应包含元数据(总数、页码、限制)
|
||||
63
docs/zh-CN/rules/common/performance.md
Normal file
63
docs/zh-CN/rules/common/performance.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# 性能优化
|
||||
|
||||
## 模型选择策略
|
||||
|
||||
**Haiku 4.5** (具备 Sonnet 90% 的能力,节省 3 倍成本):
|
||||
|
||||
* 频繁调用的轻量级智能体
|
||||
* 结对编程和代码生成
|
||||
* 多智能体系统中的工作智能体
|
||||
|
||||
**Sonnet 4.5** (最佳编码模型):
|
||||
|
||||
* 主要的开发工作
|
||||
* 编排多智能体工作流
|
||||
* 复杂的编码任务
|
||||
|
||||
**Opus 4.5** (最深的推理能力):
|
||||
|
||||
* 复杂的架构决策
|
||||
* 最高级别的推理需求
|
||||
* 研究和分析任务
|
||||
|
||||
## 上下文窗口管理
|
||||
|
||||
避免使用上下文窗口的最后 20% 进行:
|
||||
|
||||
* 大规模重构
|
||||
* 跨多个文件的功能实现
|
||||
* 调试复杂的交互
|
||||
|
||||
上下文敏感性较低的任务:
|
||||
|
||||
* 单文件编辑
|
||||
* 创建独立的实用工具
|
||||
* 文档更新
|
||||
* 简单的错误修复
|
||||
|
||||
## 扩展思考 + 计划模式
|
||||
|
||||
扩展思考默认启用,最多保留 31,999 个令牌用于内部推理。
|
||||
|
||||
通过以下方式控制扩展思考:
|
||||
|
||||
* **切换**:Option+T (macOS) / Alt+T (Windows/Linux)
|
||||
* **配置**:在 `~/.claude/settings.json` 中设置 `alwaysThinkingEnabled`
|
||||
* **预算上限**:`export MAX_THINKING_TOKENS=10000`
|
||||
* **详细模式**:Ctrl+O 查看思考输出
|
||||
|
||||
对于需要深度推理的复杂任务:
|
||||
|
||||
1. 确保扩展思考已启用(默认开启)
|
||||
2. 启用 **计划模式** 以获得结构化方法
|
||||
3. 使用多轮批判进行彻底分析
|
||||
4. 使用分割角色子代理以获得多元视角
|
||||
|
||||
## 构建故障排除
|
||||
|
||||
如果构建失败:
|
||||
|
||||
1. 使用 **build-error-resolver** 智能体
|
||||
2. 分析错误信息
|
||||
3. 逐步修复
|
||||
4. 每次修复后进行验证
|
||||
31
docs/zh-CN/rules/common/security.md
Normal file
31
docs/zh-CN/rules/common/security.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 安全指南
|
||||
|
||||
## 强制性安全检查
|
||||
|
||||
在**任何**提交之前:
|
||||
|
||||
* \[ ] 没有硬编码的密钥(API 密钥、密码、令牌)
|
||||
* \[ ] 所有用户输入都经过验证
|
||||
* \[ ] 防止 SQL 注入(使用参数化查询)
|
||||
* \[ ] 防止 XSS(净化 HTML)
|
||||
* \[ ] 已启用 CSRF 保护
|
||||
* \[ ] 已验证身份验证/授权
|
||||
* \[ ] 所有端点都实施速率限制
|
||||
* \[ ] 错误信息不泄露敏感数据
|
||||
|
||||
## 密钥管理
|
||||
|
||||
* 切勿在源代码中硬编码密钥
|
||||
* 始终使用环境变量或密钥管理器
|
||||
* 在启动时验证所需的密钥是否存在
|
||||
* 轮换任何可能已泄露的密钥
|
||||
|
||||
## 安全响应协议
|
||||
|
||||
如果发现安全问题:
|
||||
|
||||
1. 立即**停止**
|
||||
2. 使用 **security-reviewer** 代理
|
||||
3. 在继续之前修复**关键**问题
|
||||
4. 轮换任何已暴露的密钥
|
||||
5. 审查整个代码库是否存在类似问题
|
||||
31
docs/zh-CN/rules/common/testing.md
Normal file
31
docs/zh-CN/rules/common/testing.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 测试要求
|
||||
|
||||
## 最低测试覆盖率:80%
|
||||
|
||||
测试类型(全部需要):
|
||||
|
||||
1. **单元测试** - 单个函数、工具、组件
|
||||
2. **集成测试** - API 端点、数据库操作
|
||||
3. **端到端测试** - 关键用户流程(根据语言选择框架)
|
||||
|
||||
## 测试驱动开发
|
||||
|
||||
强制工作流程:
|
||||
|
||||
1. 先写测试 (失败)
|
||||
2. 运行测试 - 它应该失败
|
||||
3. 编写最小实现 (成功)
|
||||
4. 运行测试 - 它应该通过
|
||||
5. 重构 (改进)
|
||||
6. 验证覆盖率 (80%+)
|
||||
|
||||
## 测试失败排查
|
||||
|
||||
1. 使用 **tdd-guide** 代理
|
||||
2. 检查测试隔离性
|
||||
3. 验证模拟是否正确
|
||||
4. 修复实现,而不是测试(除非测试有误)
|
||||
|
||||
## 代理支持
|
||||
|
||||
* **tdd-guide** - 主动用于新功能,强制执行测试优先
|
||||
26
docs/zh-CN/rules/golang/coding-style.md
Normal file
26
docs/zh-CN/rules/golang/coding-style.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Go 编码风格
|
||||
|
||||
> 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上,扩展了 Go 语言的特定内容。
|
||||
|
||||
## 格式化
|
||||
|
||||
* **gofmt** 和 **goimports** 是强制性的 —— 无需进行风格辩论
|
||||
|
||||
## 设计原则
|
||||
|
||||
* 接受接口,返回结构体
|
||||
* 保持接口小巧(1-3 个方法)
|
||||
|
||||
## 错误处理
|
||||
|
||||
始终用上下文包装错误:
|
||||
|
||||
```go
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to create user: %w", err)
|
||||
}
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
查看技能:`golang-patterns` 以获取全面的 Go 语言惯用法和模式。
|
||||
11
docs/zh-CN/rules/golang/hooks.md
Normal file
11
docs/zh-CN/rules/golang/hooks.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Go 钩子
|
||||
|
||||
> 本文件通过 Go 特定内容扩展了 [common/hooks.md](../common/hooks.md)。
|
||||
|
||||
## PostToolUse 钩子
|
||||
|
||||
在 `~/.claude/settings.json` 中配置:
|
||||
|
||||
* **gofmt/goimports**:编辑后自动格式化 `.go` 文件
|
||||
* **go vet**:编辑 `.go` 文件后运行静态分析
|
||||
* **staticcheck**:对修改的包运行扩展静态检查
|
||||
39
docs/zh-CN/rules/golang/patterns.md
Normal file
39
docs/zh-CN/rules/golang/patterns.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Go 模式
|
||||
|
||||
> 本文档在 [common/patterns.md](../common/patterns.md) 的基础上扩展了 Go 语言特定的内容。
|
||||
|
||||
## 函数式选项
|
||||
|
||||
```go
|
||||
type Option func(*Server)
|
||||
|
||||
func WithPort(port int) Option {
|
||||
return func(s *Server) { s.port = port }
|
||||
}
|
||||
|
||||
func NewServer(opts ...Option) *Server {
|
||||
s := &Server{port: 8080}
|
||||
for _, opt := range opts {
|
||||
opt(s)
|
||||
}
|
||||
return s
|
||||
}
|
||||
```
|
||||
|
||||
## 小接口
|
||||
|
||||
在接口被使用的地方定义它们,而不是在它们被实现的地方。
|
||||
|
||||
## 依赖注入
|
||||
|
||||
使用构造函数来注入依赖:
|
||||
|
||||
```go
|
||||
func NewUserService(repo UserRepository, logger Logger) *UserService {
|
||||
return &UserService{repo: repo, logger: logger}
|
||||
}
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
有关全面的 Go 模式(包括并发、错误处理和包组织),请参阅技能:`golang-patterns`。
|
||||
28
docs/zh-CN/rules/golang/security.md
Normal file
28
docs/zh-CN/rules/golang/security.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Go 安全
|
||||
|
||||
> 此文件基于 [common/security.md](../common/security.md) 扩展了 Go 特定内容。
|
||||
|
||||
## 密钥管理
|
||||
|
||||
```go
|
||||
apiKey := os.Getenv("OPENAI_API_KEY")
|
||||
if apiKey == "" {
|
||||
log.Fatal("OPENAI_API_KEY not configured")
|
||||
}
|
||||
```
|
||||
|
||||
## 安全扫描
|
||||
|
||||
* 使用 **gosec** 进行静态安全分析:
|
||||
```bash
|
||||
gosec ./...
|
||||
```
|
||||
|
||||
## 上下文与超时
|
||||
|
||||
始终使用 `context.Context` 进行超时控制:
|
||||
|
||||
```go
|
||||
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
|
||||
defer cancel()
|
||||
```
|
||||
25
docs/zh-CN/rules/golang/testing.md
Normal file
25
docs/zh-CN/rules/golang/testing.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Go 测试
|
||||
|
||||
> 本文档在 [common/testing.md](../common/testing.md) 的基础上扩展了 Go 特定的内容。
|
||||
|
||||
## 框架
|
||||
|
||||
使用标准的 `go test` 并采用 **表格驱动测试**。
|
||||
|
||||
## 竞态检测
|
||||
|
||||
始终使用 `-race` 标志运行:
|
||||
|
||||
```bash
|
||||
go test -race ./...
|
||||
```
|
||||
|
||||
## 覆盖率
|
||||
|
||||
```bash
|
||||
go test -cover ./...
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
查看技能:`golang-testing` 以获取详细的 Go 测试模式和辅助工具。
|
||||
37
docs/zh-CN/rules/python/coding-style.md
Normal file
37
docs/zh-CN/rules/python/coding-style.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# Python 编码风格
|
||||
|
||||
> 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上扩展了 Python 特定的内容。
|
||||
|
||||
## 标准
|
||||
|
||||
* 遵循 **PEP 8** 规范
|
||||
* 在所有函数签名上使用 **类型注解**
|
||||
|
||||
## 不变性
|
||||
|
||||
优先使用不可变数据结构:
|
||||
|
||||
```python
|
||||
from dataclasses import dataclass
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class User:
|
||||
name: str
|
||||
email: str
|
||||
|
||||
from typing import NamedTuple
|
||||
|
||||
class Point(NamedTuple):
|
||||
x: float
|
||||
y: float
|
||||
```
|
||||
|
||||
## 格式化
|
||||
|
||||
* 使用 **black** 进行代码格式化
|
||||
* 使用 **isort** 进行导入排序
|
||||
* 使用 **ruff** 进行代码检查
|
||||
|
||||
## 参考
|
||||
|
||||
查看技能:`python-patterns` 以获取全面的 Python 惯用法和模式。
|
||||
14
docs/zh-CN/rules/python/hooks.md
Normal file
14
docs/zh-CN/rules/python/hooks.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# Python 钩子
|
||||
|
||||
> 本文档扩展了 [common/hooks.md](../common/hooks.md) 中关于 Python 的特定内容。
|
||||
|
||||
## PostToolUse 钩子
|
||||
|
||||
在 `~/.claude/settings.json` 中配置:
|
||||
|
||||
* **black/ruff**:编辑后自动格式化 `.py` 文件
|
||||
* **mypy/pyright**:编辑 `.py` 文件后运行类型检查
|
||||
|
||||
## 警告
|
||||
|
||||
* 对编辑文件中的 `print()` 语句发出警告(应使用 `logging` 模块替代)
|
||||
34
docs/zh-CN/rules/python/patterns.md
Normal file
34
docs/zh-CN/rules/python/patterns.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Python 模式
|
||||
|
||||
> 本文档扩展了 [common/patterns.md](../common/patterns.md),补充了 Python 特定的内容。
|
||||
|
||||
## 协议(鸭子类型)
|
||||
|
||||
```python
|
||||
from typing import Protocol
|
||||
|
||||
class Repository(Protocol):
|
||||
def find_by_id(self, id: str) -> dict | None: ...
|
||||
def save(self, entity: dict) -> dict: ...
|
||||
```
|
||||
|
||||
## 数据类作为 DTO
|
||||
|
||||
```python
|
||||
from dataclasses import dataclass
|
||||
|
||||
@dataclass
|
||||
class CreateUserRequest:
|
||||
name: str
|
||||
email: str
|
||||
age: int | None = None
|
||||
```
|
||||
|
||||
## 上下文管理器与生成器
|
||||
|
||||
* 使用上下文管理器(`with` 语句)进行资源管理
|
||||
* 使用生成器进行惰性求值和内存高效迭代
|
||||
|
||||
## 参考
|
||||
|
||||
查看技能:`python-patterns`,了解包括装饰器、并发和包组织在内的综合模式。
|
||||
25
docs/zh-CN/rules/python/security.md
Normal file
25
docs/zh-CN/rules/python/security.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Python 安全
|
||||
|
||||
> 本文档基于 [通用安全指南](../common/security.md) 扩展,补充了 Python 相关的内容。
|
||||
|
||||
## 密钥管理
|
||||
|
||||
```python
|
||||
import os
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
api_key = os.environ["OPENAI_API_KEY"] # Raises KeyError if missing
|
||||
```
|
||||
|
||||
## 安全扫描
|
||||
|
||||
* 使用 **bandit** 进行静态安全分析:
|
||||
```bash
|
||||
bandit -r src/
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
查看技能:`django-security` 以获取 Django 特定的安全指南(如适用)。
|
||||
33
docs/zh-CN/rules/python/testing.md
Normal file
33
docs/zh-CN/rules/python/testing.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Python 测试
|
||||
|
||||
> 本文件在 [通用/测试.md](../common/testing.md) 的基础上扩展了 Python 特定的内容。
|
||||
|
||||
## 框架
|
||||
|
||||
使用 **pytest** 作为测试框架。
|
||||
|
||||
## 覆盖率
|
||||
|
||||
```bash
|
||||
pytest --cov=src --cov-report=term-missing
|
||||
```
|
||||
|
||||
## 测试组织
|
||||
|
||||
使用 `pytest.mark` 进行测试分类:
|
||||
|
||||
```python
|
||||
import pytest
|
||||
|
||||
@pytest.mark.unit
|
||||
def test_calculate_total():
|
||||
...
|
||||
|
||||
@pytest.mark.integration
|
||||
def test_database_connection():
|
||||
...
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
查看技能:`python-testing` 以获取详细的 pytest 模式和夹具信息。
|
||||
58
docs/zh-CN/rules/typescript/coding-style.md
Normal file
58
docs/zh-CN/rules/typescript/coding-style.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# TypeScript/JavaScript 编码风格
|
||||
|
||||
> 本文件基于 [common/coding-style.md](../common/coding-style.md) 扩展,包含 TypeScript/JavaScript 特定内容。
|
||||
|
||||
## 不可变性
|
||||
|
||||
使用展开运算符进行不可变更新:
|
||||
|
||||
```typescript
|
||||
// WRONG: Mutation
|
||||
function updateUser(user, name) {
|
||||
user.name = name // MUTATION!
|
||||
return user
|
||||
}
|
||||
|
||||
// CORRECT: Immutability
|
||||
function updateUser(user, name) {
|
||||
return {
|
||||
...user,
|
||||
name
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
使用 async/await 配合 try-catch:
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const result = await riskyOperation()
|
||||
return result
|
||||
} catch (error) {
|
||||
console.error('Operation failed:', error)
|
||||
throw new Error('Detailed user-friendly message')
|
||||
}
|
||||
```
|
||||
|
||||
## 输入验证
|
||||
|
||||
使用 Zod 进行基于模式的验证:
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod'
|
||||
|
||||
const schema = z.object({
|
||||
email: z.string().email(),
|
||||
age: z.number().int().min(0).max(150)
|
||||
})
|
||||
|
||||
const validated = schema.parse(input)
|
||||
```
|
||||
|
||||
## Console.log
|
||||
|
||||
* 生产代码中不允许出现 `console.log` 语句
|
||||
* 请使用适当的日志库替代
|
||||
* 查看钩子以进行自动检测
|
||||
15
docs/zh-CN/rules/typescript/hooks.md
Normal file
15
docs/zh-CN/rules/typescript/hooks.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# TypeScript/JavaScript 钩子
|
||||
|
||||
> 此文件扩展了 [common/hooks.md](../common/hooks.md),并添加了 TypeScript/JavaScript 特有的内容。
|
||||
|
||||
## PostToolUse 钩子
|
||||
|
||||
在 `~/.claude/settings.json` 中配置:
|
||||
|
||||
* **Prettier**:编辑后自动格式化 JS/TS 文件
|
||||
* **TypeScript 检查**:编辑 `.ts`/`.tsx` 文件后运行 `tsc`
|
||||
* **console.log 警告**:警告编辑过的文件中存在 `console.log`
|
||||
|
||||
## Stop 钩子
|
||||
|
||||
* **console.log 审计**:在会话结束前,检查所有修改过的文件中是否存在 `console.log`
|
||||
45
docs/zh-CN/rules/typescript/patterns.md
Normal file
45
docs/zh-CN/rules/typescript/patterns.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# TypeScript/JavaScript 模式
|
||||
|
||||
> 此文件在 [common/patterns.md](../common/patterns.md) 的基础上扩展了 TypeScript/JavaScript 特定的内容。
|
||||
|
||||
## API 响应格式
|
||||
|
||||
```typescript
|
||||
interface ApiResponse<T> {
|
||||
success: boolean
|
||||
data?: T
|
||||
error?: string
|
||||
meta?: {
|
||||
total: number
|
||||
page: number
|
||||
limit: number
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 自定义 Hooks 模式
|
||||
|
||||
```typescript
|
||||
export function useDebounce<T>(value: T, delay: number): T {
|
||||
const [debouncedValue, setDebouncedValue] = useState<T>(value)
|
||||
|
||||
useEffect(() => {
|
||||
const handler = setTimeout(() => setDebouncedValue(value), delay)
|
||||
return () => clearTimeout(handler)
|
||||
}, [value, delay])
|
||||
|
||||
return debouncedValue
|
||||
}
|
||||
```
|
||||
|
||||
## 仓库模式
|
||||
|
||||
```typescript
|
||||
interface Repository<T> {
|
||||
findAll(filters?: Filters): Promise<T[]>
|
||||
findById(id: string): Promise<T | null>
|
||||
create(data: CreateDto): Promise<T>
|
||||
update(id: string, data: UpdateDto): Promise<T>
|
||||
delete(id: string): Promise<void>
|
||||
}
|
||||
```
|
||||
21
docs/zh-CN/rules/typescript/security.md
Normal file
21
docs/zh-CN/rules/typescript/security.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# TypeScript/JavaScript 安全
|
||||
|
||||
> 本文档扩展了 [common/security.md](../common/security.md),包含了 TypeScript/JavaScript 特定的内容。
|
||||
|
||||
## 密钥管理
|
||||
|
||||
```typescript
|
||||
// NEVER: Hardcoded secrets
|
||||
const apiKey = "sk-proj-xxxxx"
|
||||
|
||||
// ALWAYS: Environment variables
|
||||
const apiKey = process.env.OPENAI_API_KEY
|
||||
|
||||
if (!apiKey) {
|
||||
throw new Error('OPENAI_API_KEY not configured')
|
||||
}
|
||||
```
|
||||
|
||||
## 代理支持
|
||||
|
||||
* 使用 **security-reviewer** 技能进行全面的安全审计
|
||||
11
docs/zh-CN/rules/typescript/testing.md
Normal file
11
docs/zh-CN/rules/typescript/testing.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# TypeScript/JavaScript 测试
|
||||
|
||||
> 本文档基于 [common/testing.md](../common/testing.md) 扩展,补充了 TypeScript/JavaScript 特定的内容。
|
||||
|
||||
## E2E 测试
|
||||
|
||||
使用 **Playwright** 作为关键用户流程的 E2E 测试框架。
|
||||
|
||||
## 智能体支持
|
||||
|
||||
* **e2e-runner** - Playwright E2E 测试专家
|
||||
Reference in New Issue
Block a user