编码偏好与工具约定

yunyoujun 记录 YunYouJun 在 JavaScript / TypeScript 项目中的编码偏好和工具约定。在 YunYouJun 的项目中工作、新建项目，或希望沿用同一风格时，AI 会按上下文自动加载。

调用	触发	来源
/yunyoujun	手动或 AI 自动触发	独立 Skill

安装

npx skills add YunYouJun/ai --skill=yunyoujun

涵盖内容

主题	要点
通用	代码、注释与提交信息用英文，文档用简体中文；偏好函数式和具名导出
TypeScript	interface 优先、公共 API 显式返回类型、不用 enum、import type
Vue	Vue 3 <script setup lang="ts">、宏 API、VueUse
命名	文件 kebab-case、组件 PascalCase、常量 SCREAMING_SNAKE_CASE
Git	Conventional Commits
注释与文档	注释说明原因而不是复述代码；JSDoc / TSDoc 与 Vue 组件文档规范
模块组织	按功能分组，index.ts 只做再导出
工具链	pnpm（workspace 与 catalogs）、@antfu/eslint-config、Vite、VitePress、UnoCSS、Vitest、GitHub Actions

这是个人约定。用于其他团队时，可以复制后按自己的规范修改。

完整指令

SKILL.md

---
name: yunyoujun
description: "YunYouJun's opinionated coding preferences and tooling conventions for JavaScript/TypeScript projects. Use when working on YunYouJun's projects, setting up new projects, or following YunYouJun's coding style."
metadata:
  author: YunYouJun
  version: 0.2.0
---

YunYouJun's coding preferences and tooling conventions.

## Coding Practices

### General

- Use English for code, comments, and commit messages
- Use Chinese (Simplified) for documentation and user-facing content
- Prefer functional and declarative programming patterns
- Keep files focused and single-responsibility
- Use `export default` sparingly; prefer named exports

### TypeScript

- Always use TypeScript for new projects
- Prefer `interface` over `type` for object shapes
- Use explicit return types for public APIs
- Avoid `enum`; prefer `as const` objects or union types
- Use `type` imports: `import type { Foo } from './foo'`

### Vue

- Use Vue 3 Composition API with `<script setup lang="ts">`
- Use `defineProps`, `defineEmits`, `defineModel` macros
- Prefer single-file components (`.vue`)
- Use VueUse composables when appropriate

### Naming

- Files: `kebab-case` for all files
- Components: `PascalCase` for Vue components
- Variables/functions: `camelCase`
- Constants: `SCREAMING_SNAKE_CASE` for true constants
- Types/Interfaces: `PascalCase`

### Git Commits

- Follow [Conventional Commits](https://www.conventionalcommits.org/)
- Format: `type(scope): description`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`

## Code Documentation

### Comment Guidelines

- Write comments in **English**; keep them concise and purposeful
- Use comments to explain **why**, not **what** — code should be self-explanatory
- Avoid redundant comments that merely restate the code
- Place comments on the line above the code they describe, not inline (except for brief clarifications)

```ts
// Good — explains intent
// Retry up to 3 times to handle transient network failures
await retry(fetchData, { attempts: 3 })

// Bad — restates the code
// Set count to 0
const count = 0
```

### JSDoc / TSDoc Standards

All **public** functions, classes, interfaces, and type exports must include JSDoc:

````ts
/**
 * Resolve a module path relative to the project root.
 *
 * @param name - The module specifier (e.g. `@yunyoujun/utils`)
 * @param options - Resolution options
 * @returns The absolute file path of the resolved module
 * @throws {ModuleNotFoundError} If the module cannot be located
 *
 * @example
 * ```ts
 * const path = resolveModule('@yunyoujun/utils', { root: '/app' })
 * ```
 */
export function resolveModule(name: string, options: ResolveOptions): string {
  // ...
}
````

Key rules:

- **`@param`** — describe every parameter with its purpose
- **`@returns`** — describe the return value and type
- **`@throws`** — document error conditions
- **`@example`** — provide a usage example for non-trivial APIs
- **`@see`** — link to related documentation, functions, or external references
- **`@deprecated`** — mark deprecated APIs with migration guidance
- Internal / private helpers do **not** require JSDoc (a short `//` comment suffices)

### Vue Component Documentation

Document component props, emits, and slots using TypeScript types and comments:

````vue
<script setup lang="ts">
/**
 * A reusable card component with configurable header and content.
 *
 * @example
 * ```vue
 * <BaseCard title="Hello" :closable="true" @close="onClose">
 *   <p>Content goes here</p>
 * </BaseCard>
 * ```
 */

interface Props {
  /** Card title displayed in the header */
  title: string
  /** Whether to show the close button */
  closable?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  closable: false,
})

const emit = defineEmits<{
  /** Emitted when the close button is clicked */
  close: []
}>()
</script>
````

## Module Organization

### File & Directory Structure

- **One concept per file** — each file should have a clear, single responsibility
- **Group by feature**, not by type (prefer `features/auth/` over `components/`, `services/`)
- **Index files** (`index.ts`) should only re-export; avoid putting logic in barrel files
- Use **flat structure** within a module; nest directories only when >5 related files exist

```
# Good — feature-based grouping
src/
  features/
    auth/
      composables/
        use-auth.ts
      components/
        LoginForm.vue
      types.ts
      index.ts          # re-exports only
    dashboard/
      ...

# Avoid — type-based grouping at scale
src/
  components/
    LoginForm.vue
    DashboardCard.vue
  composables/
    use-auth.ts
    use-dashboard.ts
```

## Tooling

### Package Manager

- Use **pnpm** as the package manager
- Use `pnpm` commands directly (not ni/nr)
- Use pnpm workspace for monorepos
- Use pnpm catalogs for shared dependency versions

### ESLint

- Use `@antfu/eslint-config` — no Prettier needed
- Run `pnpm lint --fix` after making changes

### TypeScript Config

Prefer the following base `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true
  }
}
```

### Build & Dev

- Use **Vite** for web projects
- Use **VitePress** for documentation sites
- Use **UnoCSS** (or Tailwind CSS) for styling
- Use **Vitest** for testing

### CI/CD

- Use **GitHub Actions** for CI
- Use `gh` CLI for GitHub operations

## References

| Topic                | Command                             |
| -------------------- | ----------------------------------- |
| Fix issues           | `/ai-coding:fix-issue`              |
| PR automation        | `/ai-coding:pr-cycle`               |
| Review feedback      | `/ai-coding:review-feedback`        |
| Copilot review reply | `/ai-coding:address-copilot-review` |
| Copilot review loop  | `/ai-coding:copilot-review-loop`    |