code-design

分类: 开发与编程 | 上传者: gotgenes | 下载: 0 | 版本: v1.0（最新）

TypeScript 约定、代码设计原则（SOLID、自文档代码、文件组织）、结构设计启发式（依赖宽度、LoD、输出参数）、pnpm 规则、ES2024 目标和 Pi SDK 模式。在实施、重构或代码审查期间加载。 --- # 代码风格在实现、重构或审查 TypeScript 代码时加载此技能。 ## 自文档化代码代码应该是它自己的主要文档。更喜欢能够揭示意图的名称——对于函数、方法、类、变量和模块。 **名称重于注释：** 如果需要注释来解释代码的作用，请提取一个命名良好的函数或重命名该符号。评论应该解释_为什么_——决策背后的推理或不明显的背景。 **适合范围的命名：**名称长度应与范围相对应。短名称（“i”、“x”、“fn”）适合小范围（循环计数器、短 lambda）。导出的函数、模块级变量和类名需要更长的描述性名称。 **文档注释：** 在生态系统需要的地方添加 JSDoc/文档字符串 — 通常在公共/导出的 API 上。当名称和签名已经传达用法时，请勿添加文档注释。 ## 代码组织

更新日志: Source: GitHub https://github.com/gotgenes/pi-packages

目录结构

当前层级: tree/main/.pi/skills/code-design/

📄 SKILL.md 7.3 KB

SKILL.md

---
name: code-design
description: |
  TypeScript conventions, code design principles (SOLID, self-documenting code, file organization),
  structural design heuristics (dependency width, LoD, output arguments),
  pnpm rules, ES2024 target, and Pi SDK patterns.
  Load during implementation, refactoring, or code review.
---

# Code Style

Load this skill when implementing, refactoring, or reviewing TypeScript code.

## Self-Documenting Code

Code should be its own primary documentation.
Prefer names that reveal intent — for functions, methods, classes, variables, and modules.

**Names over comments:** If a comment is needed to explain _what_ code does, extract a well-named function or rename the symbol.
Comments should explain _why_ — the reasoning or non-obvious context behind a decision.

**Scope-appropriate naming:** Name length should correspond to scope.
Short names (`i`, `x`, `fn`) are fine for small scopes (loop counters, short lambdas).
Exported functions, module-level variables, and class names warrant longer, descriptive names.

**Doc comments:** Add JSDoc/docstrings where the ecosystem expects them — typically on public/exported APIs.
Do not add doc comments when the name and signature already convey usage.

## Code Organization

Source files should read like a newspaper article: high-level intent at the top, progressively deeper detail as you read down.

**Public API first:** Exported functions, classes, and interfaces appear near the top so readers can scan the module's surface without wading through implementation details.

**Stepdown rule:** Each function should be followed by the helpers it calls, at the next level of abstraction — caller first, then the helpers it depends on.
Related functions that collaborate on the same data should be grouped together.

**Helpers stay in the file:** Private helper functions remain in the same file as the code that uses them.
When private helpers accumulate to the point where they warrant their own tests, extract them into a new module with its own public API.

## SOLID Principles

### Single Responsibility (SRP)

Each function, class, and module should do one thing well.
When a unit of code has multiple reasons to change, split it.
A function that parses input _and_ processes it should be two functions; a module that handles both HTTP routing and business logic should be two modules.

### Interface Segregation (ISP)

Prefer small, focused interfaces over large ones.
Clients should not be forced to depend on methods or properties they don't use.
When an interface grows, look for natural seams to split it into smaller, cohesive contracts.

### Dependency Inversion (DIP)

High-level modules should not depend on low-level modules; both should depend on abstractions.
Default to dependency injection for non-trivial dependencies — accept collaborators as parameters rather than constructing them internally.
DI is the mechanical foundation of test-driven development: without it, you cannot substitute test doubles, and without test doubles, you cannot test units in isolation.
Design for injection from the start rather than retrofitting it later.

## Structural Design

### Dependency width

Do not pass a shared dependency bag to functions that only use a subset of it.
When a function receives an object and only touches a few of its fields, the function's real dependencies are invisible.
Define a narrow interface or accept the needed values directly.

When a shared interface references a collaborator, use a narrow interface type — not the concrete class.
Concrete class types expose private fields to TypeScript's structural checker, forcing test mocks to cast or replicate internals.

### Law of Demeter

Do not reach through an injected collaborator to talk to a stranger.
If multiple callers do the same reach-through, the missing abstraction is a method on the intermediate object that delegates internally.

### Output arguments

Do not write back into a received dependency bag.
If a function sets a field on a received object, it is doing work that belongs inside the owning object.
Encapsulate the mutation behind a method.

### Scattered resets

When the same set of fields is reset to the same values in multiple places, extract a single method (`reset()`, `shutdown()`) on the owning object.

### Parameter relay

When a new parameter must flow through a callback chain, check whether the intermediaries actually need it.
If they only relay it, the parameter belongs on an object the endpoints share — not threaded through every layer.

### Structural reasons before extracting duplication

Before extracting apparent duplication into a shared abstraction, trace why the duplicates exist.
Apparent duplication may encode genuinely different logical things — different document-outline positions, different lifecycle constraints, different consumer contexts — in which case extraction creates a leaky abstraction with a discriminator parameter that exists only to paper over the difference.

When you see two pieces of similar code, ask: "If the structural context differs, what would make them differ?"
Read the surrounding layout, the call sites, the document outline.
If the difference is a real structural distinction, prefer duplication and document why.
If the difference is incidental, extract.

Sandi Metz: "duplication is far cheaper than the wrong abstraction."

## TypeScript

- Avoid `any` unless absolutely necessary.
- Use standard top-level imports only.
- Keep modules focused and composable (one concern per file).
- Prefer explicit configuration over hidden behavior.
- Business logic should be pure functions wherever possible — keep IO at the edges.
- Do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions — accept the value as a parameter.
  Reading `process.*` inside a function hides a dependency on global state and forces tests to stub or reset modules.

### Pi SDK boundaries

Keep Pi SDK imports out of business-logic modules.
Tool definitions, event handlers, and command handlers are SDK consumers — they may import SDK types directly.
The restriction targets pure helpers, utilities, and domain modules that should remain SDK-independent.
When a new capability is needed in a library module, accept it as a parameter or callback — do not reach for the Pi SDK directly.

When writing event handlers that consume Pi SDK types, prefer lean local payload interfaces over full SDK event types.
The SDK may not export all event interfaces, and exported types often require fields the handler does not read.
Define a minimal interface with only the fields the handler uses.

When writing `promptGuidelines` for a tool registration, name the tool in every bullet — Pi flattens all tools' guidelines into one `Guidelines:` block without per-tool attribution ([earendil-works/pi#4879](https://github.com/earendil-works/pi/issues/4879)).

## Tooling

- This project uses **pnpm** exclusively (`"packageManager"` in root `package.json`; `pnpm-lock.yaml`).
  Use `pnpm run`, `pnpm exec`, and `pnpm add` — never `npm` or `npx`.
- The tsconfig target is ES2024 (`noEmit: true`).
  ES2023 APIs (`findLast`, `findLastIndex`, `toReversed`, `toSorted`, `toSpliced`, `with`) and ES2024 APIs (`Promise.withResolvers`, `Object.groupBy`, `Map.groupBy`, `Array.fromAsync`) are available and preferred.
  Do not use APIs introduced after ES2024.

登录后下载/点赞/收藏 ❤ 10 | ★ 0

code-design

目录结构

SKILL.md

举报内容

提示