开源优先守则 huguangyu666/open-source-first-skill

开源优先（禁止造轮子 Skills）

面向 AI Coding Agent 的工程实战防造轮子守则调研先行 · 开源道德 · 经济学公理 · 三阶防御模型

License: MIT
PRs Welcome
Support

📌 核心宗旨

在真实软件交付中，AI 最致命的毛病是“急于敲代码”和“从零手搓一切”。
无论是技术细节上的劣质手写（如手写拖拽、日期计算、虚拟滚动），还是高难特效的瞎搞（如凭空手搓黑洞 Shader），亦或是产品架构上的盲目自嗨（如试图单人手搓 IM 挑战 Slack、手搓 Agent 单挑 Codex）——这不仅导致复刻精度差、漏洞百出，更在疯狂烧毁极其昂贵的大模型输出 Token！

本项目为 Coding Agent（Claude Code / DeepSeek Harness / Cursor 等）量身打造了一套工业级【开源生态优先】与【调研先行】规约，将 AI 从一个蹩脚的“劣质轮子工”，蜕变为清醒的“架构师与高质量开源代码移植专家”。

⭐️ 实战第一铁律：做事之前必须调研 (Research Before Action)

未谋先动是万恶之源。任何非微小任务，严禁在未经调研前直接提笔写实现代码！
花费 500 廉价 Input Token 做好前置调研，能彻底避免后续因方向跑偏、API 幻觉或盲目手搓浪费 50,000+ 昂贵 Output Token。
尤其当当前模型的单点推理或图形/算法能力有限时，借力 GitHub 上由前沿模型或领域专家开源的高水准先验，是唯一理智且具有降维打击优势的选择。

典型对照：以“在天体/物理模拟器中加入黑洞”为例
* ❌ 错误做法（蛮力手搓）：自以为是地凭空推导引力透镜偏折与片元光线步进。耗费数万昂贵 Token，换来的是严重掉帧、失真变形的假圆圈与无休止的报错调试。
* ✅ 正确做法（调研先验并移植）：先去 GitHub / Shadertoy 调研检索，锁定成熟开源标杆（如业内前沿模型 GPT-6 Astra 或图形学大牛开源的黑洞演示）；无损提取其核心片元 Shader 与度规算法资产，在当前项目中快速完成胶水适配与工程改造，多快好省，一次成型！

在进入具体编码前，Agent 必须强制执行双轨调研（Dual-Track Research）并在回复开头简明汇报调研结论：

[接收开发需求] │ ▼ ┌────────────────────────────────────────────────────────┐ │ 1. 内部工程调研 (Internal Research) │ │ 检查 package.json / pyproject.toml / go.mod 及目录 │ │ 摸清底细：当前项目已有技术栈？版本号？已有可用工具轮子？│ └────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ 2. 外部生态调研 (External Research) │ │ 借助 web_search / web_fetch 检索社区事实标准与神级实现 │ │ 摸清行情：公认最优解是谁？最新 API 是什么？谁踩过大坑？│ └────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ 3. 调研结论先行对齐 (Sync Findings First) │ │ 先向用户输出简明调研报告：现状 + 方案对比 + 推荐路径 │ └────────────────────────────────────────────────────────┘ │ ▼ [方案敲定后，才允许精准落笔]

💰 底层经济学公理：输入 Token 远比输出廉价，复制移植远胜现场手搓

在大模型实际计费与运行性能中，存在一个压倒性的客观规律：

| 关键维度 | 输入（Input / Context Prefill） | 输出（Output / Autoregressive Generation） |
| API 计费单价 | 极度便宜（通常是输出的 1/3 ~ 1/5；命中 Cache 更是只有 1/10 ~ 1/20） | 昂贵高昂（全网最贵计费项，是调用成本的大头） |
| 推理时延 | 瞬间并行吃进（吃进几千 Token 源码只需几百毫秒） | 逐字解码慢如蜗牛（受限显存带宽，耗时数分钟） |
| 产物确定性 | 100% 工业级可靠（经过社区成千上万开发者验证的生产代码） | 随机浮动且充满隐蔽缺陷（现场瞎猜，容易漏掉边界细节） |

🔥 经济学法则：拿廉价的“输入 Token”通过 web_fetch 读取成熟开源实现，AI 仅需输出几十 Token 的胶水适配代码；让 AI 从零敲出上千行原生代码，是在用全网最贵、最慢、最不确定的“输出 Token”去重新发明早已有之的轮子！

⚖️ 工程底线与开源道德：双重致敬铁律 (Dual-Track Attribution)

享用开源成果却隐瞒来源、把别人的心血假装成自己凭空手搓，是极其恶劣的“代码洗稿（Code Laundering）”行为！
真正的顶级工程师从不掩饰对巨人的借鉴，相反，在代码和文档中堂堂正正致敬开源，是专业素养与道德担当的最高体现。

凡是在工程中引用的核心开源库、移植的 GitHub/Shadertoy 算法与 Shader、借鉴的先验方案，必须执行双重强制致敬：

1. 代码文件头注释 (In-Code Header) 在生成的代码文件顶部，必须保留结构化致敬注释块： /**

* 来源致敬 (Open-Source Attribution)
* 原作项目: [仓库名称 / Shadertoy 作品标题]
* 原作者: [原作者 GitHub ID / 署名]
* 原始链接: [GitHub 仓库 URL / Shadertoy 链接]
* 开源协议: [MIT / Apache-2.0 / BSD / CC-BY 等]
* 移植说明: [简要说明为当前项目所做的胶水适配、框架封装或改动]

/

2. 项目 README 鸣谢章节 (Project README Credits) 用户和同行通常只看项目门面！ 必须在项目 README.md 文末显式追加 ## 鸣谢与开源致敬 (Acknowledgements & Credits) 章节：

鸣谢与开源致敬 (Acknowledgements & Credits)

本项目在研发过程中深度站在了开源社区巨人的肩膀上，特别致敬以下优秀作品与作者：
- [模块/特效名称，如：黑洞引力透镜着色器]：核心算法与片元实现移植自 @作者名 的开源作品 作品标题，采用 [开源协议] 授权。
- [核心功能模块，如：列表拖拽排序]：基于 @dnd-kit/core 构建，感谢作者提供的无障碍与触摸交互支持。

🛡️ 防造轮子三阶防御模型

┌────────────────────────────────────────────────────────────────────────┐
│ Tier 3: 系统与产品级 (Product/System Level) │ │ 典型场景：从零手搓 IM、自研协作文档、从零造 Agent 试图单挑 Codex/Claude Code │ │ 核心机制：【冷水协议】量化 Token 与工程鸿沟，引导基于成熟开源基座二次开发 │ ├────────────────────────────────────────────────────────────────────────┤ │ Tier 2: 特效与代码级 (Assets, Shaders & Visuals) │ │ 典型场景：黑洞模拟、引力透镜、GLSL 复杂流体、3D 宇宙星空、Raymarching │ │ 核心机制：【高效先验移植】用便宜输入抓取高赞代码，轻量输出 + 双重致敬署名 │ ├────────────────────────────────────────────────────────────────────────┤ │ Tier 1: 依赖与工程组件级 (Libraries & Components) │ │ 典型场景：拖拽排序、虚拟列表、日期计算、表单验证 (zod)、JWT 加密 │ │ 核心机制：【生态避坑与胶水集成】查 package.json，避开过时库，只写业务胶水│ └────────────────────────────────────────────────────────────────────────┘

⚠️ 适用边界说明：实战交付 vs 纯跑分测试

本 Skill 是【实战工程交付专属】：在实际项目开发中，核心衡量指标是交付效率、代码质量、维护成本与 Token 开销。在生产中为了秀模型肌肉而徒手造轮子是严重的工程失职。
* 大模型能力基准测试（Benchmark）脱离通道：如果用户当前对话的本意是为了跑分、极限压力测试、探究大模型能否徒手编写黑洞 Shader 或复杂底层算法，请切换至未加载 Harness 或关闭本技能的纯裸模型环境进行单测。

📂 文件目录结构

open-source-first/
├── SKILL.md # AI 技能核心定义（Agent 自动加载执行规约） ├── README.md # 中文说明文档（默认首页） ├── README.en.md # 英文说明文档（English Documentation） └── references/ ├── common-ecosystems.md # Tier 1: 废弃老库避坑表与现代事实标准对照 ├── creative-and-shaders.md # Tier 2: 黑洞/特效/Shader 极低 Token 移植指南 ├── product-level-alternatives.md # Tier 3: IM/Agent/协作文档开源天花板清单 └── search-playbook.md # 原生搜索与直连抓取官方文档/Shader战术手册

🚀 各平台安装与使用

1. DeepSeek Harness (DSH)
将本项目放入全局目录： ~/.dsh/skills/open-source-first/ 或 ~/.agents/skills/open-source-first/ 系统会自动热重载识别。

2. Claude Code CLI
放入用户全局或项目目录：用户全局生效： ~/.claude/skills/open-source-first/

仅当前项目生效： /.claude/skills/open-source-first/

3. Cursor / Windsurf
将 SKILL.md 的正文内容直接粘贴到项目根目录的 .cursorrules 或 .windsurfrules 文件中即可。

📄 开源许可证

本项目遵循 MIT License 开源。