mcpField
C
core-principles

core-principles

github.com/loxosceles-dev开发132 次安装
代码仓库

关于 core-principles

core-principles 是适用于各类项目的软件开发指导技能，规定纯函数、显式错误处理、代码组织、命名和安全实践。它强调缺少必需配置或数据时明确失败，并允许结合项目背景说明偏离原则的理由。

主要功能

  1. 01优先使用纯函数
  2. 02缺少必需配置时明确报错
  3. 03按职责组织代码
  4. 04使用有意义的变量名
  5. 05遵循凭据与密钥安全基线

适用场景

  1. 01制定团队通用编码约定
  2. 02检查默认值是否掩盖配置或数据错误
  3. 03梳理模块职责与错误处理方式
  4. 04审查密钥和凭据的存放与获取

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/loxosceles-dev/dev-skills --skill core-principles

安装后在 Claude Code 中输入/core-principles确认已加载。

详细介绍

核心原则

这是一项严格的准则。 请遵循这些规则。如果其他技能与以下规则冲突，以本技能为准。

适用于所有项目的基本准则。

重要提示：这些是指导原则，而非绝对规则。项目背景很重要。如需偏离，请说明理由和权衡。

示例说明：代码示例可能会使用特定语言（JavaScript、Python 等）以便于说明，但这些原则普遍适用。请根据项目所用语言和背景调整模式。

1. 优先使用纯函数

辅助函数应将数据作为参数接收，而不是从全局变量或环境中读取。

// ✅ Preferred: Pure, testable, moveable
function buildResourceName(environment: string, type: string, name: string): string {
  return `${environment}-${type}-${name}`;
}

// ⚠️ Less ideal: Reads from global
const ENV = process.env.ENVIRONMENT;
function buildResourceName(type: string, name: string): string {
  return `${ENV}-${type}-${name}`;
}

必须使用非纯函数时（AWS 调用、数据库访问）：尽量缩小作用范围，并在可行时将客户端作为参数传入。

2. 不要使用静默默认值——尽早失败，明确报错

几乎不要使用回退值。缺少配置、数据字段或出现意外状态时，应立即失败，并给出明确且有意义的错误信息。

// ❌ Silent fallback — masks misconfiguration
const region = process.env.AWS_REGION || 'us-east-1';

// ✅ Fail fast with actionable error
if (!process.env.AWS_REGION) {
  throw new Error('AWS_REGION is required. Set in environment or SSM.');
}
const region = process.env.AWS_REGION;

# ❌ Silent default — hides corrupt data
source = status.get("scrape_source", "")

# ✅ Required field — let it fail if missing
source = status["scrape_source"]

唯一的例外——面向用户的弹性处理：API 端点和前端代码不得因单条错误记录或缺少非必要字段而整体崩溃。在这些情况下：

  • 在循环／条目级别捕获错误（而非字段级别）
  • 记录完整错误及可识别的上下文（pk、sk 等）
  • 跳过错误记录，正常返回其余内容
  • 不要在每个字段上散布 .get("field", "") 默认值——这会悄无声息地掩盖数据问题
# ✅ Correct: required fields fail loud, but one bad record doesn't crash the endpoint
for item in items:
    try:
        result.append(format_item(item))  # format_item uses item["field"] — no defaults
    except (KeyError, ValueError):
        logging.exception("Skipping corrupt item: pk=%s sk=%s", item.get("pk"), item.get("sk"))

如果不确定某项是否属于“非必要”，请先暂停并讨论。默认做法是明确报错。

3. 代码结构与组织

尽量保持文件结构一致，并明确划分职责。

推荐的文件结构：

  1. 导入
  2. 环境变量校验（冷启动时尽早失败）
  3. 常量
  4. AWS 客户端和开销较大的初始化
  5. 类型／接口
  6. 纯辅助函数
  7. 非纯函数（AWS 调用、I/O）
  8. 入口（handler、main 等）

职责分离：

  • 尽量将架构、提示词和业务逻辑分别放在不同文件中
  • 避免混合无关功能
  • 在职责分离与过度拆分之间保持平衡

函数声明：

  • 简单／内联：箭头函数 const fn = () => {}
  • 复杂逻辑：function fn() {} 形式的函数声明

4. 配置中的项目标识符

避免对项目标识符进行硬编码。请改用配置。

// ❌ Avoid
const paramPath = `/myapp/${environment}/api-key`;

// ✅ Preferred
const PROJECT_ID = process.env.PROJECT_ID;
const paramPath = `/${PROJECT_ID}/${environment}/api-key`;

5. 错误处理

默认做法是尽早失败并明确报错。优雅降级属于少见的例外，而非常规做法。

  • 抛出错误／崩溃：缺少配置、缺少必需的数据字段、设置无效、关键依赖异常。这是默认做法。
  • 记录日志并跳过条目：仅适用于面向用户的边界（API 响应、前端渲染），此时单个错误条目不能导致整个响应失败。在条目级别捕获错误，记录上下文并跳过该条目。
  • 切勿：散布静默默认值（.get("field", "")）来避免错误。这会掩盖问题。
  • 务必：在错误信息中提供可采取行动的上下文——涉及哪条记录、哪个字段以及预期内容。

6. 变量命名

使用有意义的变量名。除非属于约定俗成的用法，否则避免使用单字母名称。

// ❌ Avoid
arr.map((a) => a.id);
catch (e) { console.error(e); }

// ✅ Preferred
users.map((user) => user.id);
catch (err) { console.error(err); }

可接受的缩写：err、evt、req、res、ctx、idx、fn

例外：数学公式（x、y、i、j）、简单的箭头函数（[1,2,3].map(n => n * 2)）

7. 安全基线

  • 不要将机密、API 密钥和凭证存入代码库
  • 使用 AWS Secrets Manager 或 SSM Parameter Store（SecureString）
  • 在运行时而非构建时获取机密
  • 优先使用 IAM 角色，而不是硬编码凭证
  • 按环境区分资源和机密

渐进式改进

如果开发者纠正了本技能本应避免的行为，请建议对此技能进行具体修订，以防止今后再次出现同样的问题。

评论

支持 Markdown