secret-sauce

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Secret Sauce

核心开发秘籍

Best practices, rules, and templates extracted from real production projects.

从实际生产项目中提炼的最佳实践、规则和模板。

Quick Reference

快速参考

Category	Reference File
Tech Stack	`references/tech-stack.md`
Project Setup	`references/claude-md-template.md`
Project Tracking	`references/project-tracking.md`
Coding Standards	`references/coding-standards.md`
Centralization	`references/centralization-patterns.md`
Tailwind v4	`references/tailwind-v4.md`
AI Development	`references/ai-flow-patterns.md`
Data Fetching	`references/data-fetching.md`
Git Workflow	`references/git-workflows.md`
Testing	`references/testing-patterns.md`
Supabase	`references/supabase-patterns.md`
Deployment	`references/deployment-patterns.md`
Browser Tools	`references/browser-automation.md`
Versioning	`references/version-management.md`

分类	参考文档
技术栈	`references/tech-stack.md`
项目搭建	`references/claude-md-template.md`
项目追踪	`references/project-tracking.md`
编码标准	`references/coding-standards.md`
集中化模式	`references/centralization-patterns.md`
Tailwind v4	`references/tailwind-v4.md`
AI开发	`references/ai-flow-patterns.md`
数据获取	`references/data-fetching.md`
Git工作流	`references/git-workflows.md`
测试	`references/testing-patterns.md`
Supabase	`references/supabase-patterns.md`
部署	`references/deployment-patterns.md`
浏览器工具	`references/browser-automation.md`
版本管理	`references/version-management.md`

Framework Rules

框架规则

Framework	Rule File
TypeScript	`rules/typescript.md`
Next.js	`rules/nextjs.md`
React	`rules/react.md`
Supabase	`rules/supabase.md`
Security	`rules/security.md`

框架	规则文档
TypeScript	`rules/typescript.md`
Next.js	`rules/nextjs.md`
React	`rules/react.md`
Supabase	`rules/supabase.md`
安全	`rules/security.md`

Templates

模板

Template	Purpose
`templates/CLAUDE.md.template`	Project configuration starter
`templates/settings.json.template`	Permission configuration
`templates/project-plan.md.template`	Project planning document
`templates/implementation-plan.md.template`	Technical implementation plan
`templates/code-review.md.template`	Code review summary
`templates/changelog.md.template`	Project changelog

模板	用途
`templates/CLAUDE.md.template`	项目配置起始模板
`templates/settings.json.template`	权限配置模板
`templates/project-plan.md.template`	项目规划文档模板
`templates/implementation-plan.md.template`	技术实现方案模板
`templates/code-review.md.template`	代码评审总结模板
`templates/changelog.md.template`	项目变更日志模板

Usage

使用方法

Starting a New Project

启动新项目

Copy
```
templates/CLAUDE.md.template
```
to your project root as
```
CLAUDE.md
```
Customize sections for your stack

Reference specific rules:

~/.claude/skills/secret-sauce/rules/typescript.md

将
```
templates/CLAUDE.md.template
```
复制到项目根目录并重命名为
```
CLAUDE.md
```
根据你的技术栈自定义各章节内容

参考具体规则文档：

~/.claude/skills/secret-sauce/rules/typescript.md

Setting Up Permissions

权限设置

Copy

templates/settings.json.template

.claude/settings.json

Adjust permissions for your workflow

将

templates/settings.json.template

复制到

.claude/settings.json

根据你的工作流调整权限配置

Project Documentation

项目文档

Use templates for consistent project documentation:

```
project-plan.md.template
```
for planning
```
implementation-plan.md.template
```
for technical specs
```
code-review.md.template
```
for reviews

使用模板保持项目文档的一致性：

```
project-plan.md.template
```
用于项目规划
```
implementation-plan.md.template
```
用于技术规格说明
```
code-review.md.template
```
用于代码评审

Key Patterns

核心模式

CLAUDE.md Structure

CLAUDE.md 结构

Every project CLAUDE.md should include:

YAML frontmatter (title, status, owner, tags)
Quick Reference section with key commands
Active/Pending/Completed projects
Stack-specific guidelines
Development patterns

每个项目的CLAUDE.md应包含以下内容：

YAML前置元数据（标题、状态、负责人、标签）
包含关键命令的快速参考章节
进行中/待处理/已完成项目列表
技术栈专属指南
开发模式说明

Git Workflow

Git工作流

Commit format:
```
<type>(<scope>): <description>
```
Never commit without confirmation
Branch naming:
```
feature/<name>
```
,
```
fix/<name>
```
PR template with summary and test plan

提交格式：
```
<type>(<scope>): <description>
```
未经确认绝不要提交代码
分支命名规则：
```
feature/<name>
```
、
```
fix/<name>
```
拉取请求（PR）模板需包含总结和测试计划

Centralization Pattern

集中化模式

All configuration in

@/config

typescript

import { env, isProduction, getServiceUrl } from '@/config';

所有配置统一存放于

@/config

：

typescript

import { env, isProduction, getServiceUrl } from '@/config';

Configuration Hierarchy

配置层级

Database configuration (system_configuration table)
Environment variables (.env.local)
Hardcoded defaults

Secrets (API keys) →

.env.local

only Configs (models, URLs) → Database with fallback

数据库配置（system_configuration表）
环境变量（.env.local）
硬编码默认值

密钥（API密钥）→ 仅存于

.env.local

配置项（模型、URL）→ 存储于数据库并设置回退值

Testing Standards

测试标准

Target: >90% coverage
Use Jest with 30s timeout for ML operations
Add new test directories to test runners
Security tests required for auth/validation

目标覆盖率：>90%
针对机器学习操作，使用Jest并设置30秒超时
将新测试目录添加到测试运行器中
认证/验证模块必须包含安全测试

AI Flow Pattern

AI流程模式

Zod schemas for input/output
Prompt builder functions
OpenAI SDK v6 with
```
zodResponseFormat()
```
Error handling with Result types
Server action wrapper

使用Zod schema定义输入/输出
提示词构建函数
搭配
```
zodResponseFormat()
```
使用OpenAI SDK v6
使用Result类型处理错误
服务器动作包装器

Data Fetching

数据获取

Always pass
```
signal
```
to fetch calls
Use
```
isAbortError()
```
to handle cancellation
Memoize fetch options to prevent refetches
Use
```
usePolling
```
for dashboards with visibility-aware intervals

所有fetch调用必须传递
```
signal
```
参数
使用
```
isAbortError()
```
处理取消操作
对fetch选项进行 memoize 以避免重复请求
针对仪表盘，使用
```
usePolling
```
实现可见性感知的轮询间隔

Security Checklist

安全检查清单

Strict TypeScript (no
```
any
```
)
Zod input validation
Safe property access:
```
Object.prototype.hasOwnProperty.call()
```
XSS prevention on all user inputs
Rate limiting in API routes

严格模式TypeScript（禁止使用
```
any
```
类型）
Zod输入验证
安全属性访问：
```
Object.prototype.hasOwnProperty.call()
```
对所有用户输入进行XSS防护
API路由中添加速率限制