tinkering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tinkering

实验探索

Overview

概述

Structured experimentation framework. When uncertain about an approach, don't hack at production code - create an isolated sandbox, try freely, then graduate successful experiments or discard failed ones cleanly.

Core principle: The output of tinkering is knowledge, not production code. A successful experiment teaches you how to solve the problem. The actual implementation happens after, informed by what you learned.

这是一个结构化的实验框架。当你不确定某种方案是否可行时，不要直接修改生产代码——创建一个隔离的沙箱环境，自由尝试，之后再将成功的实验成果正式应用到生产环境，或者干净地丢弃失败的实验。

核心原则： 实验探索的产出是知识，而非生产代码。一次成功的实验会教会你如何解决问题，实际的生产实现将在你所学的基础上开展。

When to Use

适用场景

Situation	Tinkering?	Why
"Will this library work for our use case?"	Yes	Unknown outcome, need to explore
"Which of these 3 approaches is fastest?"	Yes	Comparing multiple options
"How do I integrate this API?"	Yes	Technical spike, learning-focused
"Add a login button to the header"	No	Clear requirement, use git branch
"Fix the null pointer on line 42"	No	Debugging, not experimenting
"Refactor auth module to use JWT"	Maybe	If approach uncertain, spike first

场景	是否适合实验探索？	原因
“这个库是否适用于我们的业务场景？”	是	结果未知，需要探索验证
“这3种方案中哪一种速度最快？”	是	需要对比多种选项
“我该如何集成这个API？”	是	属于技术调研，以学习为核心
“在头部导航栏添加登录按钮”	否	需求明确，应使用Git分支
“修复第42行的空指针异常”	否	属于调试，而非实验探索
“重构认证模块以使用JWT”	可能	如果方案不确定，先开展技术调研

Workflow

工作流

Phase 1: Setup Sandbox

阶段1：搭建沙箱环境

Create isolated experiment environment:

bash

undefined

创建隔离的实验环境：

bash

undefined

1. Create experiment directory

1. 创建实验目录

mkdir -p _experiments/{experiment-name}

2. Add to .gitignore (if not already present)

2. 将目录添加到.gitignore（如果尚未添加）

grep -qxF '_experiments/' .gitignore 2>/dev/null || echo '_experiments/' >> .gitignore

3. Create manifest (first time only)

3. 创建实验清单（首次使用时）

See MANIFEST.md template below

参考下方的MANIFEST.md模板


**MANIFEST.md template** (create at `_experiments/MANIFEST.md`):
```markdown


**MANIFEST.md模板**（创建于`_experiments/MANIFEST.md`）：
```markdown

Experiment Log

实验日志

Active

进行中

{experiment-name}

Date: YYYY-MM-DD
Hypothesis: What we're trying to learn
Status: active
Result: (pending)

日期: YYYY-MM-DD
假设: 我们试图验证或学习的内容
状态: 进行中
结果: （待更新）

Completed

已完成


**Rules:**
- NEVER modify production files during tinkering
- ALL experiment code goes inside `_experiments/{name}/`
- Copy source files into sandbox if you need to modify them

---


**规则：**
- 实验探索期间绝不能修改生产文件
- 所有实验代码必须放在`_experiments/{name}/`目录下
- 如果需要修改现有文件，请将文件复制到沙箱中再操作

---

Phase 2: Hypothesize

阶段2：明确实验假设

Before writing any code, state clearly:

Question : What specific question are we answering?
Success  : How will we know it works?
Time box : Maximum time to spend (default: 30 min)
Scope    : Which files/areas are involved?

Write this in

_experiments/{name}/HYPOTHESIS.md

or as a top comment.

Example:

Question : Can we replace moment.js with date-fns and reduce bundle size?
Success  : Bundle decreases >20%, all date formatting still works
Time box : 20 minutes
Scope    : src/utils/date.ts, package.json

在编写任何代码前，明确以下内容：

问题 : 我们要解决的具体问题是什么？
成功标准 : 如何判断实验成功？
时间限制 : 最长实验时长（默认：30分钟）
范围 : 涉及哪些文件或领域？

将以上内容写入

_experiments/{name}/HYPOTHESIS.md

或作为代码顶部注释。

示例：

问题 : 我们能否用date-fns替代moment.js以减小包体积？
成功标准 : 包体积减少超过20%，所有日期格式化功能正常运行
时间限制 : 20分钟
范围 : src/utils/date.ts, package.json

Phase 3: Experiment

阶段3：开展实验

Build freely in the sandbox.

Modifying existing code:

bash

undefined

在沙箱环境中自由尝试。

修改现有代码：

bash

undefined

Copy the file(s) you need to change

复制需要修改的文件

cp src/utils/date.ts _experiments/date-fns-migration/date.ts

Edit the copy freely - zero risk to production

自由编辑副本——完全不会影响生产环境


**New feature exploration:**
```bash


**探索新功能：**
```bash

Create new files directly in sandbox

在沙箱中直接创建新文件

touch _experiments/websocket-poc/server.ts touch _experiments/websocket-poc/client.ts


**Library evaluation:**
```bash

touch _experiments/websocket-poc/server.ts touch _experiments/websocket-poc/client.ts


**评估第三方库：**
```bash

Minimal test script in sandbox

在沙箱中编写极简测试脚本

touch _experiments/redis-eval/test_redis.py

Use isolated dependencies (venv, local node_modules)

使用隔离的依赖环境（如venv、本地node_modules）


**Multi-approach comparison:**

_experiments/caching-spike/ approach-a-redis/ approach-b-memory/ approach-c-sqlite/ COMPARISON.md # Side-by-side evaluation


**Rules during experimentation:**
- Stay in sandbox - never touch production files
- Quick and dirty is fine - this is throwaway code
- Document learnings as you go
- Stop at time box, even if incomplete - partial answers are still answers

---


**多方案对比：**

_experiments/caching-spike/ approach-a-redis/ approach-b-memory/ approach-c-sqlite/ COMPARISON.md # 多方案对比评估


**实验期间规则：**
- 始终在沙箱中操作，绝不能触碰生产文件
- 快速实现即可——实验代码是一次性的
- 随时记录实验心得
- 到时间限制就停止，即使未完成——部分结论也有价值

---

Phase 4: Evaluate

阶段4：评估实验结果

Assess results against the hypothesis.

Checklist:

Did the experiment answer the original question?
Does it meet the success criteria from Phase 2?
Any unexpected side effects or constraints discovered?
Is the approach feasible for production implementation?
What's the estimated effort to implement properly?

Update MANIFEST.md:

markdown

- **Result**: SUCCESS - date-fns reduced bundle by 34%, all tests pass
- **Status**: graduated
- **Notes**: Need to handle timezone edge case in formatRelative()

Decision:

Positive result -> Phase 5, Path A (Graduate)
Negative result -> Phase 5, Path B (Discard)
Inconclusive -> Extend time box OR try different approach

对照实验假设评估结果。

检查清单：

实验是否回答了最初的问题？
是否达到了阶段2设定的成功标准？
是否发现了意外的副作用或限制？
该方案是否适合在生产环境中实现？
正式实现的预估工作量是多少？

更新MANIFEST.md：

markdown

- **结果**: 成功 - date-fns将包体积减少了34%，所有测试通过
- **状态**: 已应用到生产
- **备注**: 需要处理formatRelative()中的时区边缘情况

决策：

结果积极 -> 进入阶段5，路径A（应用到生产）
结果消极 -> 进入阶段5，路径B（丢弃实验）
结果不明确 -> 延长时间限制或尝试其他方案

Phase 5: Graduate or Discard

阶段5：应用成果或丢弃实验

Path A: Graduate (success)

路径A：应用成果（实验成功）

Load reference:

references/graduation-checklist.md

Quick summary:

Do NOT copy-paste experiment code directly into production
Re-implement properly using what you learned
Write proper tests for the production implementation
Apply code standards (experiment was quick & dirty, production shouldn't be)
Reference experiment in commit message for context

参考文档：

references/graduation-checklist.md

简要流程：

绝不能直接将实验代码复制粘贴到生产环境
基于实验中学到的知识，重新规范实现
为生产实现编写完整测试
遵循代码规范（实验代码可以快速粗糙，但生产代码必须规范）
在提交信息中引用实验以提供上下文

Path B: Discard (failed)

路径B：丢弃实验（实验失败）

Failed experiments are valuable - they tell you what NOT to do.

Update MANIFEST.md with failure reason and learnings
Delete experiment files:
```
rm -rf _experiments/{name}/
```
Or keep briefly if learnings are worth referencing

失败的实验同样有价值——它们会告诉你哪些方案不可行。

在MANIFEST.md中更新失败原因和实验心得
删除实验文件：
```
rm -rf _experiments/{name}/
```
如果实验心得有参考价值，可暂时保留文件

Phase 6: Cleanup

阶段6：清理环境

bash

undefined

bash

undefined

Remove completed experiment

删除已完成的实验

rm -rf _experiments/{experiment-name}/

Update MANIFEST.md - move entry to "Completed" section

更新MANIFEST.md - 将实验条目移至“已完成”部分


**MANIFEST.md after cleanup:**
```markdown


**清理后的MANIFEST.md示例：**
```markdown

Completed

已完成

date-fns-migration (2025-01-15)

date-fns迁移（2025-01-15）

GRADUATED - Implemented in commit abc123
Learnings: date-fns 3x smaller, timezone handling needs explicit config

已应用到生产 - 在提交abc123中完成实现
心得：date-fns体积是moment.js的1/3，时区处理需显式配置

graphql-evaluation (2025-01-10)

GraphQL评估（2025-01-10）

DISCARDED - Too much overhead for our simple REST API
Learnings: REST + OpenAPI better fit for <20 endpoints

---

已丢弃 - 对于我们的简单REST API来说，GraphQL开销过大
心得：端点数量少于20个时，REST + OpenAPI更合适

---

Quick Reference

快速参考

Setup      ->  mkdir _experiments/{name}, add to .gitignore
Hypothesize ->  Question + success criteria + time box
Experiment  ->  Build in sandbox (never touch production)
Evaluate    ->  Check against success criteria
Graduate    ->  Re-implement properly in production
Cleanup     ->  Remove files, update manifest

搭建环境      ->  创建_experiments/{name}目录，添加到.gitignore
明确假设     ->  确定问题、成功标准、时间限制
开展实验      ->  在沙箱中操作（绝不能触碰生产文件）
评估结果      ->  对照成功标准检查
应用成果      ->  基于实验知识规范实现生产代码
清理环境      ->  删除实验文件，更新实验清单

Edge Cases

边缘场景处理

Needs database changes: Use separate test DB or schema prefix. Document in hypothesis.

Needs running server: Run from sandbox, use different port to avoid conflicts.

Multiple concurrent experiments: Each gets own subdirectory. MANIFEST tracks all.

Experiment grows into real feature: Graduate it. Don't let experiments become shadow production code.

Team member needs to see experiment: Push to feature branch (temporarily track

_experiments/

) or share via patch.

需要修改数据库： 使用独立的测试数据库或表前缀，并在实验假设中说明。

需要运行服务器： 在沙箱中启动服务器，使用不同端口避免冲突。

多用户同时开展实验： 每个实验使用独立子目录，实验清单跟踪所有实验。

实验演变为正式功能： 将其应用到生产环境，不要让实验代码变成影子生产代码。

团队成员需要查看实验： 临时将_experiments/目录推送到功能分支，或通过补丁文件分享。