@captain_z/zsk 0.1.0

package/templates/project-init/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md — <项目名>
+
+> Claude Code 进入本项目时自动读取的会话指令。其他 harness（Codex `AGENTS.md` / Gemini `GEMINI.md`）镜像核心语义。
+
+## 项目身份
+
+- **名称**：<项目名>
+- **类型**：<microfrontend / monolith / library / cli>
+- **技术栈**：见 [`project-config.md`](./project-config.md)（frontmatter `stack.*`）
+
+## 本项目使用 zsk skill set
+
+通过 `@captain_z/zsk add` 安装（`~/.claude/skills/` 或 `./.claude/skills/`）。运行时自动发现；手动触发写 "用 `zsk:<name>`"。
+
+**常用 skill 组合**（见 `npx @captain_z/zsk list`）：
+
+- 启动任一变更：`zsk:feature` / `zsk:bugfix` / `zsk:refactor`
+- 7 阶段：`zsk:proposal` → `zsk:spec` → `zsk:design` → `zsk:coding` → `zsk:reviewing` → `zsk:verify` → `zsk:archive`
+- 任务：`zsk:task` / `zsk:task-structure` / `zsk:task-tracking`（含 §6 每任务交互契约）/ `zsk:task-evidence` / `zsk:dor-dod`
+- 前端扩展：`zsk:spec-frontend` / `zsk:design-frontend` / `zsk:review-frontend` / `zsk:feature-tasks-frontend`
+
+## 项目事实源
+
+| 文件 / 目录 | 作用 |
+| --- | --- |
+| [`project-config.md`](./project-config.md) | 机械配置（`{{config.*}}` 占位符的解析源） |
+| [`.raws/`](./.raws/) | 原始事实源（SRS / FIGMA-INDEX / api-contracts / design-assets） |
+| `docs/system/` | 系统级决策（ADR / architecture / glossary / nfr-baseline） |
+| `SYSTEM-SPEC.md`（可选） | 团队共享的项目硬约束，覆写 zsk skill 默认 |
+
+## 规约优先级（冲突时上位胜出）
+
+1. 用户会话显式指令
+2. 本 `CLAUDE.md` 的项目指令
+3. `SYSTEM-SPEC.md`（若存在）
+4. `project-config.md`
+5. `docs/system/*`（ADR / architecture / NFR baseline）
+6. zsk skills（已安装）
+7. 平台级 skill（`~/.claude/skills/*` 非 zsk 的）
+8. 工具默认行为
+
+## 交互契约（LLM 执行任务时）
+
+见 `zsk:task-tracking` §6：**每单任务执行完 → 更新状态 + 填证据 → 短汇报 → 等人类确认 → 再推下一个**，不自动连跑。
+例外：纯读取任务 / 用户显式授权"连跑 N 个" / CI 自动化任务。

package/templates/project-init/project-config.md

@@ -0,0 +1,296 @@
+---
+# ============================================================
+# Project Config Template（新项目适配模板）
+#
+# 用法：
+# 1. 新项目从本模板拷贝到仓库根 `project-config.md`
+# 2. 填写 frontmatter 实际值（替换 `<fill-me>`）
+# 3. 按正文模板补齐 Import Origins / 禁用清单 / 选型理由等叙述
+# 4. 本 skill set 中所有 `{{config.*}}` 占位符会解析 frontmatter 对应键
+#
+# 设计：frontmatter = 机械查表（AI 替换占位符）；正文 = 叙述与理由
+# 优先级：本文件被项目 CLAUDE.md / SYSTEM-SPEC.md 覆写
+# ============================================================
+
+meta:
+  project_name: "<fill-me>"
+  project_type: "<fill-me>"                   # microfrontend / monolith / library / cli
+  project_role: "<fill-me>"                   # consumer / provider / shell / standalone
+  shell_host: ""                              # 若是 microfrontend 的 provider，填宿主应用
+  created: "<YYYY-MM-DD>"
+  maintainers:
+    - "<Your Name> <<you@example.com>>"
+
+# ------------------------------------------------------------
+# 路径（项目文档与代码布局）
+# ------------------------------------------------------------
+paths:
+  srs: "<fill-me>"                            # e.g., .raws/SRS.md / docs/PRD.md
+  figma_index: "<fill-me>"                    # e.g., .raws/FIGMA-INDEX.md
+  api_contracts: "<fill-me>"                  # e.g., .raws/api-contracts
+  design_assets: "<fill-me>"                  # e.g., .raws/design-assets
+  system_docs: "docs/system"
+  modules: "docs"
+  services_root: "<fill-me>"                  # e.g., src/services
+  services_entry: "<fill-me>"                 # e.g., src/services/clients.ts
+  services_core: "<fill-me>"                  # e.g., src/services/core
+  module_services_pattern: "<fill-me>"        # e.g., src/pages/{module}/services
+  i18n_entry: "<fill-me>"                     # e.g., src/utils/i18n.ts
+  components_root: "<fill-me>"                # e.g., src/components
+  hooks_root: "<fill-me>"                     # e.g., src/hooks
+  path_alias_config: "tsconfig.json"
+  mf_expose_entry: ""                         # microfrontend 才填，e.g., src/app4Exposes.tsx
+
+# ------------------------------------------------------------
+# 路径别名（与 tsconfig.json / 构建工具一致）
+# ------------------------------------------------------------
+path_aliases:
+  "@services/*": "<fill-me>"
+  "@components/*": "<fill-me>"
+  "@utils/*": "<fill-me>"
+  "@pages/*": "<fill-me>"
+
+# ------------------------------------------------------------
+# Import 起源（coding 阶段硬约束 — 具体示例与理由见正文）
+# ------------------------------------------------------------
+import_origins:
+  ui_components:
+    must_from: "<fill-me>"                    # e.g., @your-org/ui
+    forbidden: []                             # 其他 UI 库
+  i18n:
+    must_from: "<fill-me>"                    # e.g., @utils/i18n
+    forbidden_direct: []
+  http_clients:
+    must_from: "<fill-me>"                    # e.g., @services/clients
+    forbidden: []
+  http_factory:
+    must_from: "<fill-me>"                    # e.g., 公司 SDK 包名
+    wrapper: "<fill-me>"                      # e.g., @services/core/client-factory
+  module_services:
+    location: "<fill-me>"                     # e.g., src/pages/{module}/services/
+    must_consume_from: "<fill-me>"            # 通常等于 paths.services_entry 的别名
+
+# ------------------------------------------------------------
+# 项目命令（package.json 实际脚本名）
+# ------------------------------------------------------------
+scripts:
+  install: "<fill-me>"                        # e.g., npm install / yarn / pnpm install
+  dev: "<fill-me>"
+  build: "<fill-me>"
+  lint: "<fill-me>"
+  type_check: "<fill-me>"                     # e.g., npm run type-check / npx tsc --noEmit
+  test: "<fill-me>"
+  format: "<fill-me>"
+
+# ------------------------------------------------------------
+# 技术栈
+# ------------------------------------------------------------
+stack:
+  framework: "<fill-me>"                      # e.g., React 18 / Vue 3 / Svelte 5
+  language: "TypeScript"
+  language_strict: true
+  build_tool: "<fill-me>"                     # Webpack / Vite / Rspack
+  build_wrapper: ""                           # 公司封装；若无留空
+  css: "<fill-me>"                            # Less / Sass / CSS Modules / Tailwind
+  css_ext: "<fill-me>"                        # less / scss / module.css / css
+  css_naming: "BEM"
+  state_local: "useState"
+  state_async: "<fill-me>"                    # TanStack Query / SWR / RTK Query
+  state_shared: "<fill-me>"                   # Jotai / Zustand / Context
+  state_forbidden: []
+  router: "<fill-me>"                         # react-router / TanStack Router
+  router_version: ""                          # 锁定版本（若有）
+  ui_lib: "<fill-me>"                         # e.g., @your-org/ui
+  ui_lib_display_name: "<fill-me>"
+  http_client: "<fill-me>"                    # 统一 HTTP 入口函数签名
+  http_client_import: "<fill-me>"
+  sdk_packages: []
+  global_sdk: ""                              # 类似 @seeyon/global 的全局 SDK
+  global_sdk_import: ""
+  test_framework: "<fill-me>"                 # Jest / Vitest
+  test_utils: "<fill-me>"
+
+# ------------------------------------------------------------
+# 国际化
+# ------------------------------------------------------------
+i18n:
+  enabled: true
+  entry: "<fill-me>"
+  namespace: "<fill-me>"                      # key 前缀
+  languages: ["zh_CN", "en"]                  # 第一个为基线
+  fallback_required: true
+  icu_for_plurals: true
+
+# ------------------------------------------------------------
+# Git / 分支 / Commit
+# ------------------------------------------------------------
+git:
+  main_branch: "<fill-me>"                    # main / master / develop / test
+  feature_branch_pattern: "feature/{scope}"
+  fix_branch_pattern: "fix/{issue-id}"
+  refactor_branch_pattern: "refactor/{scope}"
+  docs_branch_pattern: "docs/{topic}"
+  commit_style: "conventional"
+  commit_scopes: []
+
+# ------------------------------------------------------------
+# 部署 / 环境
+# ------------------------------------------------------------
+deploy:
+  environments:
+    - { name: "dev",  domain: "<fill-me>" }
+    - { name: "test", domain: "<fill-me>" }
+    - { name: "pre",  domain: "<fill-me>" }
+    - { name: "prod", domain: "<fill-me>" }
+  pipeline: "<fill-me>"                       # Jenkins / GitHub Actions / GitLab CI
+
+# ------------------------------------------------------------
+# 外部工具 / MCP
+# ------------------------------------------------------------
+tools:
+  figma_mcp: ""
+  design_tool: "Figma"
+
+# ------------------------------------------------------------
+# 质量基线
+# ------------------------------------------------------------
+quality:
+  performance:
+    lcp_target: 2500
+    inp_target: 200
+    cls_target: 0.1
+    bundle_size_max_kb: 500
+  accessibility:
+    wcag_level: "AA"
+    mandatory: true
+  testing:
+    unit_coverage_min: 80
+    critical_branch_coverage_min: 85
+    new_code_coverage: 100
+  security:
+    cve_response_hours: 24
+    forbidden_licenses: ["GPL", "AGPL"]
+
+# ------------------------------------------------------------
+# 浏览器 / 响应式
+# ------------------------------------------------------------
+compat:
+  browsers:
+    - { name: "Chrome",  min_versions: 2, priority: "P0" }
+    - { name: "Edge",    min_versions: 2, priority: "P0" }
+    - { name: "Safari",  min_versions: 2, priority: "P1" }
+    - { name: "Firefox", min_versions: 2, priority: "P1" }
+  breakpoints:
+    mobile: null
+    tablet: 768
+    desktop: 1024
+    wide: 1440
+  min_resolution:
+    desktop: [1280, 720]
+    laptop: [1366, 768]
+
+# ------------------------------------------------------------
+# 示例值（文档举例用）
+# ------------------------------------------------------------
+examples:
+  module_pascal: "FeatureA"
+  module_kebab: "feature-a"
+  module_camel: "featureA"
+  service_name: "ExampleService"
+  service_request: "exampleRequest"
+  leaf_key: "empty"
+  issue_id: "PROJ-123"
+---
+
+# Project Config — {项目名}
+
+> **来源**：`docs/.best-practices/_config/project-config.template.md`
+> **位置**：拷贝到仓库根 `project-config.md`（工具中立，Claude Code / Codex / 其他 agent 均可读）
+> **Git 状态**：建议加入 `.gitignore`（AI 本地配置）；若团队共享则提交
+> **消费方式**：frontmatter = `{{config.*}}` 机械锚点 → 正文 = 叙述与理由
+> **优先级**：本文件被项目 `CLAUDE.md` / `SYSTEM-SPEC.md` 覆写
+
+---
+
+## 1. Import 起源（coding 阶段硬约束）
+
+> 违反会被 Reviewing / Verify 阻断。对应 frontmatter `import_origins.*`。
+
+| 能力 | 必须 import 自 | 禁止 | 示例 |
+| --- | --- | --- | --- |
+| UI 组件 | `{{import_origins.ui_components.must_from}}` | 其他 UI 库 | `import { Button } from '...';` |
+| 国际化 | `{{import_origins.i18n.must_from}}` | 直接调第三方 i18n 库 | `import { t } from '...';` |
+| HTTP 客户端（业务代码） | `{{import_origins.http_clients.must_from}}` | 裸 fetch / axios / 新建 request 实例 | `import { fooRequest } from '...';` |
+| HTTP 工厂（仅 services 层内部） | `{{import_origins.http_factory.must_from}}` + `{{import_origins.http_factory.wrapper}}` | 业务代码直接 import 本层 | 见下方代码示例 |
+| 模块级 service | consume `{{import_origins.module_services.must_consume_from}}` | 重建 request 实例 | 见下方代码示例 |
+
+### 1.1 Services 三层分工（以实际项目填充代码示例）
+
+```ts
+// Layer 1 — {services_entry}（唯一对外出口）
+// 从全局 SDK 拿 raw request，经 client-factory 包装后 export
+```
+
+```ts
+// Layer 2 — 模块级 service ({module_services.location})
+// 只 consume clients；禁止重建 request 实例
+```
+
+```ts
+// Layer 3 — 业务组件
+// 通过模块 service 间接消费；不直接 import clients
+```
+
+---
+
+## 2. 必用封装
+
+| 场景 | 必用封装 | 位置 | 理由 |
+| --- | --- | --- | --- |
+| HTTP 请求 | `<项目 HTTP 工厂>` | `<path>` | 统一错误码 / 超时 / 拦截 |
+| i18n 文案 | `t(key, fallback, values?)` | `{{paths.i18n_entry}}` | 多语同步 / fallback / ICU |
+| 错误边界 | 模块入口 `ErrorBoundary` | 模块 `index.tsx` | 统一错误 UI + 上报 |
+
+---
+
+## 3. 禁用清单（Red Lines）
+
+### 3.1 禁用的包 / 库
+
+| 包 / 模式 | 禁用原因 | 替代 | ADR |
+| --- | --- | --- | --- |
+| {填写项目实际禁用项，如 Redux} | {过重 / 重复 / 冲突} | {替代方案} | {ADR-XXXX} |
+
+### 3.2 禁用的语法 / 模式
+
+| 模式 | 原因 | 替代 |
+| --- | --- | --- |
+| `any` / `as any` / `@ts-ignore` | 绕开类型系统 | 具体类型 / `unknown` + 收窄 |
+| 新增硬编码文案 | i18n 违规 | `t(key, fallback)` |
+| `dangerouslySetInnerHTML`（未经审） | XSS 风险 | 文本节点 / ADR 豁免 |
+| 裸 `console.log` 进生产 | 日志泄漏 | 封装 logger |
+
+---
+
+## 4. 技术栈 Pin 版本（有 ADR 保护）
+
+| 维度 | 选型 / 版本 | 锁定方式 | ADR |
+| --- | --- | --- | --- |
+| 框架 | `{{stack.framework}}` | `package.json` | — |
+| 路由 | `{{stack.router}} {{stack.router_version}}` | {锁定方式} | {ADR-XXXX} |
+| 样式 | `{{stack.css}}` | {锁定方式} | {ADR-XXXX} |
+| UI | `{{stack.ui_lib}}` | `package.json` | {ADR-XXXX} |
+
+---
+
+## 5. 与上位规约的关系
+
+| 本文件（项目本地 AI 配置） | 其他文件 |
+| --- | --- |
+| `{{config.*}}` 机械替换 + 项目硬约束叙述 | `SYSTEM-SPEC.md` — 团队共享规约 |
+| 本地不入库（除非团队共享） | `CLAUDE.md` — 入库，AI 会话指令 |
+| 一处改全局生效 | `docs/.best-practices/*` — 通用方法论 |
+
+**冲突时**：`CLAUDE.md` > 本文件 > `docs/.best-practices/*`。
+
+项目硬约束新增 / 变更走 ADR（见 [`../system/adr.md`](../system/adr.md)）。