@lark-apaas/coding-steering 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @lark-apaas/coding-steering
+
+Stack-specific steering content for [miaoda coding](https://code.byted.org/apaas/miaoda-coding) templates.
+
+Consumed by [miaoda-cli](https://code.byted.org/apaas/miaoda-cli) at `app init` time and synced into the user project's `.agent/steering/`. **Not a runtime dependency** — no entry in user `package.json`.
+
+## Layout
+
+```
+steering/
+├── _common/
+│   └── skills/                    # cross-stack shared skills
+├── <stack>/
+│   ├── tech.md                    # always-loaded, injected into agent system prompt
+│   └── skills/<id>/SKILL.md       # progressive disclosure, triggered by description match
+└── ...
+```
+
+Top-level directory names (other than `_common`) ARE the stackId — discovery is by directory convention, no central manifest.
+
+## Sync mapping (executed by miaoda-cli)
+
+| Source in this package | Destination in user project |
+|---|---|
+| `steering/<stack>/tech.md` | `.agent/steering/tech.md` |
+| `steering/<stack>/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
+| `steering/_common/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
+
+When a `_common` skill and a stack-specific skill share the same `<id>`, the stack-specific one wins.
+
+## Writing rules
+
+See [steering-authoring-rules.md](https://code.byted.org/apaas/miaoda-coding/blob/main/docs/steering-authoring-rules.md). Core principles:
+
+- **Forward-compatible always:** never break old usage, only `@deprecated` it
+- **Latest is safe:** existing user projects can always pull the latest version
+- **Describe by current structure:** when introducing version-dependent guidance, write for the stack's current layout
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@lark-apaas/coding-steering",
+  "version": "0.1.0-alpha.1",
+  "description": "Stack-specific steering content for miaoda-coding templates",
+  "type": "module",
+  "files": ["steering"],
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md'"
+  },
+  "devDependencies": {
+    "markdownlint-cli": "^0.47.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": ["miaoda", "coding-steering"],
+  "license": "MIT"
+}

package/steering/_common/skills/react-hook-best-practices/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: react-hook-best-practices
+description: "Use when writing or reviewing React hooks: useEffect dependencies, useMemo/useCallback, custom hooks. 触发词：useEffect, useMemo, useCallback, 自定义 hook, React hook 规范"
+steering: true
+steering-topic: react_hook_best_practices
+---
+
+# React Hook 最佳实践
+
+## 一、useEffect 依赖
+
+```tsx
+// ❌ 错：缺依赖
+useEffect(() => {
+  fetchUser(userId);
+}, []);
+
+// ✅ 对：完整依赖
+useEffect(() => {
+  fetchUser(userId);
+}, [userId]);
+```
+
+- 始终用 `eslint-plugin-react-hooks` 自动检查依赖
+- 不要为了"避免重复执行"省略依赖——用 cleanup function 或 ref 处理
+
+## 二、useMemo / useCallback
+
+只在以下场景使用：
+
+- 计算昂贵（实测 >5ms）
+- 引用稳定性影响下游（passed as prop to memoized child）
+
+默认**不预先优化**——大多数计算不需要 memo。
+
+## 三、自定义 hook
+
+- 命名以 `use` 开头：`useDebounce` / `useLocalStorage`
+- 单一职责，<50 行
+- 内部不直接操作 DOM（用 ref + useEffect）

package/steering/_common/skills/tailwind-conventions/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tailwind-conventions
+description: "Use when styling components with Tailwind CSS: class organization, custom utilities, dark mode, responsive design. 触发词：Tailwind, className 顺序, 暗色模式, 响应式设计"
+steering: true
+steering-topic: tailwind_conventions
+---
+
+# Tailwind 约定
+
+## 一、className 顺序
+
+按下列顺序写 class：
+
+1. layout（display / position / flex / grid）
+2. spacing（margin / padding / gap）
+3. sizing（width / height）
+4. typography（text-* / font-*）
+5. color（bg-* / text-* / border-*）
+6. interactive（hover: / focus: / active:）
+7. responsive（md: / lg:）
+
+```tsx
+<div className="flex items-center gap-2 px-4 py-2 text-sm text-gray-900 bg-white hover:bg-gray-50 md:px-6">
+```
+
+## 二、暗色模式
+
+- 用 `next-themes` 提供 `dark` class 切换
+- 颜色用 `bg-white dark:bg-gray-900` 双写
+
+## 三、避免硬编码颜色
+
+❌ `text-[#3b82f6]`
+✅ `text-blue-500`
+
+如确需自定义色，加到 `tailwind.config.js` 的 theme.colors。

package/steering/html/tech.md

@@ -0,0 +1,3 @@
+# html stack
+
+Placeholder for v0.1. Stack technical overview will be written in v0.3.

package/steering/vite-react/skills/client-coding-guide/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: client-coding-guide
+description: "Use when implementing client-side features in vite-react stack: components, hooks, routing, state management. 触发词：客户端开发, React 组件, 页面路由, hooks, vite, vite-react"
+steering: true
+steering-topic: client_coding_guide
+---
+
+# Client Coding Guide (vite-react)
+
+## 一、组件分层
+
+```
+ui/        ← shadcn-ui 基础组件，源码自动生成，禁止直接编辑
+components/ ← 业务组件，组合 ui/ 实现具体场景
+pages/     ← 路由页面，组合多个 components/ 构建完整界面
+```
+
+## 二、State 管理
+
+- 局部 state 用 `useState`
+- 共享 state 优先用 React Context
+- 避免引入 Redux/Zustand 等全局 store（v0.1 不依赖）
+
+## 三、表单实现模板
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1, '必填'),
+  email: z.string().email(),
+});
+
+type FormValues = z.infer<typeof schema>;
+
+export function MyForm() {
+  const form = useForm<FormValues>({ resolver: zodResolver(schema) });
+  const onSubmit = (values: FormValues) => { /* ... */ };
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <input {...form.register('name')} />
+      {/* ... */}
+    </form>
+  );
+}
+```

package/steering/vite-react/skills/component-conventions/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: component-conventions
+description: "Use when creating or refactoring React components: naming, file structure, props typing, default values. 触发词：组件命名, props 类型, 组件文件结构, React 最佳实践"
+steering: true
+steering-topic: component_conventions
+---
+
+# Component Conventions (vite-react)
+
+## 一、文件结构
+
+每个组件一个目录：
+
+```
+components/
+└── UserCard/
+    ├── index.tsx           # 组件主文件
+    ├── UserCard.test.tsx   # 测试（可选）
+    └── types.ts            # 局部类型（可选）
+```
+
+## 二、命名
+
+- 组件名 PascalCase：`UserCard`、`StatusBadge`
+- 文件名跟组件名一致：`UserCard.tsx`
+- props 接口：`UserCardProps`
+
+## 三、props 类型
+
+```tsx
+interface UserCardProps {
+  user: User;
+  onSelect?: (id: string) => void;
+  className?: string;
+}
+
+export function UserCard({ user, onSelect, className }: UserCardProps) {
+  // ...
+}
+```
+
+- **强制带 `className?: string`**——所有业务组件都应允许外部传 className
+- **回调用 `onXxx` 命名**——`onSelect` / `onChange` / `onSubmit`
+
+## 四、默认导出 vs 命名导出
+
+- 业务组件**命名导出**：`export function UserCard ...`
+- 入口/页面组件可以默认导出

package/steering/vite-react/tech.md

@@ -0,0 +1,35 @@
+# Vite React Stack
+
+## 技术栈
+
+- 构建：Vite 8 + TypeScript
+- UI：React 19 + shadcn-ui + Radix Primitives + Tailwind CSS v4
+- 路由：react-router-dom v7
+- 表单：react-hook-form + zod
+- 图表：echarts-for-react / recharts
+- 动画：framer-motion / gsap
+
+## 目录结构
+
+```
+my-app/
+├── client/
+│   ├── src/
+│   │   ├── components/   # 业务组件
+│   │   ├── ui/           # shadcn-ui 基础组件（不要直接改）
+│   │   ├── pages/        # 路由页面
+│   │   ├── hooks/        # 自定义 hooks
+│   │   └── lib/          # 工具函数
+│   ├── index.html
+│   └── public/
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+## 核心约定
+
+1. **shadcn-ui 组件不直接改源码**——需要变化时通过 className / variant props 控制
+2. **样式优先用 Tailwind utility**，避免写 CSS module
+3. **表单始终用 react-hook-form + zod**——不要直接操作 input value
+4. **图表 ECharts 优先 echarts-for-react**——React 18 严格模式下要小心 echarts instance 的初始化