---
name: dev-principles
description: "Development principles: ubiquitous language, tracer bullets, deep modules, unidirectional dependencies. Use before non-trivial feature work, cross-module changes, refactoring, dependency or module-boundary changes, or design review; not needed for simple single-point fixes. 开发原则：统一语言、贯通路径、深模块、单向依赖。在开始非琐碎的功能开发、跨模块修改、重构、调整依赖或模块边界、设计评审前使用；简单的单点修复不需要。"
title: dev-principles
canonical_url: https://skilld.dev/gh/z2014/skills/dev-principles
last_updated: 2026-10-19T12:00:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install z2014/skills/dev-principles`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/dev-principles`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/z2014/skills/dev-principles) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/dev-principles`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/dev-principles --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/dev-principles --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 开发原则

用准确的语言定义问题，用最小的真实路径验证方向，用简单的接口封装复杂性，用单向的依赖控制变化的影响范围。

## 统一语言（Ubiquitous Language）

- 动手前查阅项目术语表（默认 `docs/glossary.md`，不存在时在首次需要时创建）。沿用已有术语，在需求、代码标识符、测试和文档中保持一致。
- 区分相近概念，例如任务、执行、尝试。不同理解会导致不可逆或代价高的差异时，先澄清；否则写明假设后继续。
- 术语只在其业务上下文内统一，不同上下文可以使用不同模型。
- 新增术语或发现冲突时，更新术语表：名称、含义、代码标识符、易混淆的近义词。

## 贯通路径（Tracer Bullet）

- 动手前写出：选定的路径、经过的层、哪些部分用替身、哪些集成暂不验证。
- 选择范围小、能验证关键不确定性的用例，先打通它需要的每一层，再扩展其他场景。
- 路径可以窄，但要保留它需要的校验、权限和错误处理。这条路径的代码要留作骨架继续演进；只用于学习的原型要明确标注为可丢弃。
- 用端到端测试或真实运行证明路径已打通。单条路径成功不代表整个系统正确。
- 单点 bug 修复不需要贯通路径：先复现，再修复，最后验证。

## 深模块（Deep Modules）

- 先复用现有模块。按职责和所需知识划分边界，不按执行顺序拆分。
- 接口要说明行为、错误和使用前提；尽量通过设计消除错误情况，而不是交给调用者处理。
- 自查：
  - 调用者不读实现，能否正确使用？
  - 新增的层是否隐藏了复杂度？只做转发的层不要加。
  - 同一规则或格式是否散落在多个模块？
  - 调用者是否必须按固定顺序组合多个调用？
- 贯通路径跑通后，扩展前检查一遍边界，清理为了打通而临时加的浅层。

## 单向依赖（Unidirectional Dependencies）

- 依赖只朝一个方向：入口、界面和基础设施依赖业务核心；业务核心不依赖框架、数据库、界面或外部服务的具体实现。
- 模块之间不形成环。新增 import 或调用前，确认不会让两个模块互相依赖。
- 下层需要通知上层或调用外部能力时，由下层定义接口、回调或事件，上层实现或订阅；不反向 import 上层。
- 依赖朝更稳定的方向：容易变化的模块依赖不容易变化的模块，而不是相反。
- 项目已有分层或依赖检查规则时，遵守并运行检查（例如 dependency-cruiser、import-linter、ArchUnit）；没有时，在评审中检查新增依赖的方向。
- 贯通路径为了先跑通而临时引入的反向依赖或循环依赖，在扩展前清理。

## 交付

说明已完成的行为、验证方式和结果、未覆盖的限制，以及本次新增或修改的术语。只实现当前需求，不提前增加没有依据的通用能力。
