engineering-quality
Project lint, format, and git hooks setup using Biome and Lefthook. Use when modifying biome.json, lefthook config, or troubleshooting pre-commit/pre-push hooks.
ソース情報
- リポジトリ
- recca0120/code-quest
- ソースの最終更新活動
- 2026年5月7日 14:06
- 検出された SKILL.md の言語
- 中国語
- スター
- 11
- フォーク
- 2
インストール方法
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
ソースファイルを確認
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SKILL.md を表示中
SKILL.md
ソースの指示 · 読み取り専用プレビュー- name
- engineering-quality
- description
- Project lint, format, and git hooks setup using Biome and Lefthook. Use when modifying biome.json, lefthook config, or troubleshooting pre-commit/pre-push hooks.
# Engineering Quality
## 用途
專案的 lint、format、git hooks、DI 等品質基礎建設的設定和使用指南。
## 何時使用
- 新增或修改 biome / lefthook 設定
- 設定 DI（dependency injection）模式
- 處理 pre-commit / pre-push hook 問題
- 新增或修改 zod runtime schema validation
---
## Biome（Lint + Format）
### 設定檔
`/biome.json`（root level，server + client 共用）：
```json
{
"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
"organizeImports": { "enabled": true },
"formatter": {
"indentStyle": "space",
"indentWidth": 2,
"lineWidth": 100
},
"linter": {
"rules": {
"recommended": true,
"suspicious": { "noExplicitAny": "warn" }
}
},
"javascript": {
"formatter": { "quoteStyle": "single", "semicolons": "always" }
}
}
```
### 常用命令
```bash
# 檢查（lint + format）
pnpm biome check .
# 自動修正
pnpm biome check --write .
# 只檢查特定檔案
pnpm biome check apps/server/src/chat/parsers/
# CI 模式（不修正，只報錯）
pnpm biome ci .
```
---
## Lefthook（Git Hooks）
### 設定檔
`/lefthook.yml`：
```yaml
pre-commit:
parallel: true
commands:
biome:
glob: "*.{ts,tsx,js,json}"
run: pnpm biome check --write {staged_files}
stage_fixed: true
typecheck-server:
glob: "apps/server/**/*.ts"
run: pnpm --filter server exec tsc --noEmit
typecheck-client:
glob: "apps/web/**/*.{ts,tsx}"
run: pnpm --filter client exec tsc --noEmit
pre-push:
parallel: true
commands:
test-server:
run: pnpm --filter server exec vitest run
test-client:
run: pnpm --filter client exec vitest run
```
### 管理命令
```bash
# 安裝 hooks
pnpm lefthook install
# 跳過 hooks（緊急情況）
git commit --no-verify -m "emergency fix"
# 手動執行 pre-commit
pnpm lefthook run pre-commit
```
---
## DI 模式（Inversify 7）
專案使用 **Inversify 7** 做 server-side dependency injection。詳細 patterns 請參考 `/inversify-di` skill。
### 核心原則
1. **Interface first** — 依賴型別用 interface，不用 concrete class
2. **Symbol tokens** — 所有 binding token 定義在 `types.symbols.ts`
3. **Lazy factory resolution** — `toDynamicValue` 內的依賴在 factory 被呼叫時才 resolve
4. **Test via rebindSync** — 測試中用 `createTestContainer` + `rebindSync` 替換依賴
5. **Composition root** — 只在 `container.ts` 和 entry point 呼叫 `container.get()`
---
## Zod Runtime Validation
### 用途
- 驗證 CLI 輸出格式是否符合預期
- 驗證 WebSocket 事件格式
- 開發時 early warning，production 可關閉
### Schema 位置
```
apps/server/src/chat/schemas/
├── claude.ts # Claude CLI 原始輸出
├── gemini.ts # Gemini CLI 原始輸出
├── events.ts # 統一的 ChatStreamEvent
└── index.ts # re-export
```
### 使用方式
```typescript
import { ClaudeStreamLine } from '../schemas/claude';
// 嚴格驗證（開發/測試時）
const parsed = ClaudeStreamLine.parse(json);
// 寬鬆驗證（production）
const result = ClaudeStreamLine.safeParse(json);
if (!result.success) {
logger.warn('Unexpected CLI format', result.error);
}
```
---
## 從 ESLint 遷移到 Biome
### 步驟
1. 安裝 biome：`pnpm add -D @biomejs/biome --workspace-root`
2. 建立 `/biome.json`
3. 執行 `pnpm biome check --write .` 修正所有檔案
4. 刪除 `.eslintrc.cjs`（server + client）
5. 移除 eslint 相關 devDependencies
6. 更新 `package.json` scripts
### 注意事項
- Biome 和 ESLint 規則不完全對應，遷移後需要 review diff
- Biome 的 import 排序規則與 ESLint 不同
- `noExplicitAny` 設為 `warn` 而非 `error`，因為專案中大量使用 `any`
---
## 相關
- 計畫文件：`docs/plans/fixture-driven-testing.md`
- Fixture-Driven TDD：`/fixture-driven-tdd`
- Parser 開發：`/parser-development`
GitHubで見る