shareful-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shareful Create

Shareful 创建指南

Create SHARE.md files that follow shareful.ai quality standards from first draft through validation.

从初稿到验证，创建符合shareful.ai质量标准的SHARE.md文件。

Reference Files

参考文件

File	Read When
`references/frontmatter-guide.md`	Writing or reviewing frontmatter fields
`references/writing-sections.md`	Writing the four body sections
`references/quality-examples.md`	Calibrating quality or reviewing a draft share
`references/validation-checklist.md`	Final validation pass before finishing

文件	适用场景
`references/frontmatter-guide.md`	编写或审核前置元数据字段时
`references/writing-sections.md`	编写四个正文章节时
`references/quality-examples.md`	校准内容质量或审核分享初稿时
`references/validation-checklist.md`	完成前的最终验证环节

Creation Workflow

创建工作流

Copy this checklist to track progress:

text

- [ ] Step 1: Ensure shares repo context exists
- [ ] Step 2: Classify the problem and choose solution type
- [ ] Step 3: Draft frontmatter
- [ ] Step 4: Draft the required body sections
- [ ] Step 5: Create SHARE.md
- [ ] Step 6: Validate with checklist

复制以下检查清单以跟踪进度：

text

- [ ] 步骤1：确保Shares仓库上下文已配置
- [ ] 步骤2：对问题进行分类并选择解决方案类型
- [ ] 步骤3：编写前置元数据
- [ ] 步骤4：编写必填正文章节
- [ ] 步骤5：创建SHARE.md文件
- [ ] 步骤6：使用检查清单验证

Step 1: Ensure Shares Repo Context Exists

步骤1：确保Shares仓库上下文已配置

Check if a shares repo is configured:

Read
```
~/.shareful/config.json
```
for the
```
sharesRepo
```
path
If set, verify the path contains a
```
shares/
```
directory
If not set, run
```
npx shareful-ai init [name]
```
to create and configure a repo

The

init

command creates the directory structure and saves the repo path to config.

检查是否已配置shares仓库：

读取
```
~/.shareful/config.json
```
文件中的
```
sharesRepo
```
路径
若已设置，验证该路径下是否包含
```
shares/
```
目录
若未设置，运行
```
npx shareful-ai init [name]
```
命令创建并配置仓库

init

命令会创建目录结构，并将仓库路径保存到配置文件中。

Step 2: Classify Problem and Choose Solution Type

步骤2：问题分类与解决方案类型选择

Determine what was solved and choose the correct

solution_type

Type	Use when	Title convention
`fix`	Directly resolves a bug or error	"Fix ..."
`workaround`	Temporarily bypasses a known issue	"Workaround for ..."
`pattern`	Reusable coding pattern or architecture	"Use ...", "Implement ..."
`reference`	Lookup guide or cheat sheet	"Guide to ...", "Reference for ..."
`config`	Configuration change resolving a setup issue	"Configure ..."

Most shares are

fix

type. Use

pattern

only when the solution generalizes beyond a single error.

明确要解决的问题，并选择正确的

solution_type

：

类型	适用场景	标题命名规范
`fix`	直接修复某个bug或错误	"Fix ..."（修复...）
`workaround`	临时绕过已知问题	"Workaround for ..."（...的临时解决方案）
`pattern`	可复用的编码模式或架构	"Use ..."（使用...）, "Implement ..."（实现...）
`reference`	查询指南或速查表	"Guide to ..."（...指南）, "Reference for ..."（...参考手册）
`config`	通过配置变更解决安装问题	"Configure ..."（配置...）

大多数分享内容属于

fix

类型。仅当解决方案可推广到多个场景时，才使用

pattern

类型，bug修复不属于此类。

Step 3: Draft Frontmatter

步骤3：编写前置元数据（Frontmatter）

Read references/frontmatter-guide.md for the complete schema and examples.

Required fields:

yaml

---
title: "Human-readable title"          # max 128 chars
slug: kebab-case-identifier             # max 64 chars, a-z 0-9 hyphens only
tags: [tag1, tag2, tag3]                # 1-10 tags, max 32 chars each, lowercase
problem: "One-sentence problem summary" # max 256 chars
solution_type: fix                      # fix | workaround | pattern | reference | config
created: 2026-02-08                     # YYYY-MM-DD
environment:                            # optional but recommended
  language: typescript
  framework: nextjs
  version: "15+"
---

Key rules:

Slug is auto-generated from title: lowercase, strip special chars, spaces to hyphens, max 64 chars
Slug MUST match the parent directory name
Problem field should include the error message or symptom for searchability
Tags should cover: primary technology, problem domain, and 1-2 descriptors

阅读references/frontmatter-guide.md获取完整的 schema 及示例。

必填字段：

yaml

---
title: "易读性标题"          # 最多128个字符
slug: 短横线分隔的标识符             # 最多64个字符，仅包含a-z、0-9和短横线
tags: [标签1, 标签2, 标签3]                # 1-10个标签，每个最多32个字符，小写
problem: "一句话问题概述" # 最多256个字符
solution_type: fix                      # 可选值：fix | workaround | pattern | reference | config
created: 2026-02-08                     # 格式：YYYY-MM-DD
environment:                            # 可选但推荐填写
  language: typescript
  framework: nextjs
  version: "15+"
---

核心规则：

Slug 由标题自动生成：转为小写，移除特殊字符，空格替换为短横线，最多64个字符
Slug 必须与父目录名称完全一致
Problem字段应包含具体错误信息或症状，以提升可搜索性
标签应涵盖：核心技术、问题领域及1-2个描述性标签

Step 4: Draft the Required Body Sections

步骤4：编写必填正文章节

Read references/writing-sections.md for templates and guidance.

Optionally read references/quality-examples.md for annotated good and bad examples.

All four sections are required:

## Problem -- Show the broken state with real code and error messages
## Solution -- Provide working code with multiple options when applicable
## Why It Works -- Explain the underlying mechanism, not just "what" but "why"
## Context -- List environment requirements, gotchas, and related tools

The body must be under 300 lines total. Aim for 60-150 lines.

阅读references/writing-sections.md获取模板及指导。

可选阅读references/quality-examples.md查看标注好的优秀及反面示例。

以下四个章节为必填项：

## 问题描述 -- 通过真实代码和错误信息展示故障状态
## 解决方案 -- 提供可运行的代码，如有多种方案可一并列出
## 原理说明 -- 解释底层机制，而非重复解决方案内容
## 环境与注意事项 -- 列出环境要求、潜在陷阱及相关工具

正文总长度不得超过300行，建议控制在60-150行。

Step 5: Create SHARE.md

步骤5：创建SHARE.md文件

Option A: Use the CLI

bash

npx shareful-ai create --title "Fix Prisma N+1 queries" --tags "prisma,database,performance" --type fix --problem "Prisma makes hundreds of queries when loading related data"

Then edit the generated

shares/<slug>/SHARE.md

to replace template content with real content.

Option B: Write directly

Create

shares/<slug>/SHARE.md

with the complete frontmatter and body. Ensure the

shares/

directory exists (run

npx shareful-ai init

if not).

选项A：使用CLI工具

bash

npx shareful-ai create --title "Fix Prisma N+1 queries" --tags "prisma,database,performance" --type fix --problem "Prisma makes hundreds of queries when loading related data"

然后编辑生成的

shares/<slug>/SHARE.md

文件，将模板内容替换为真实内容。

选项B：手动编写

创建

shares/<slug>/SHARE.md

文件，包含完整的前置元数据和正文内容。确保

shares/

目录已存在（若不存在，运行

npx shareful-ai init

命令创建）。

Step 6: Validate with Checklist

步骤6：使用检查清单验证

Read references/validation-checklist.md and run all checks.

Expected output after this step:

A complete
```
shares/<slug>/SHARE.md
```
file
Frontmatter and section structure validated
No placeholder content

阅读references/validation-checklist.md并完成所有检查项。

此步骤完成后应得到：

完整的
```
shares/<slug>/SHARE.md
```
文件
前置元数据及章节结构已验证通过
无占位符内容

Anti-patterns

常见反模式

Writing a vague problem field ("Something is broken") instead of including the actual error message
Using Why It Works to repeat the solution instead of explaining the underlying mechanism
Forgetting language labels on code blocks
Making the title too generic ("Fix TypeScript error") instead of specific ("Fix TypeScript module augmentation for third-party types")
Slug not matching the directory name
Exceeding 300 lines in the body
Using
```
pattern
```
type for what is actually a
```
fix
```
(pattern is for reusable architecture, not bug fixes)

问题描述模糊（如“某个功能坏了”），未包含具体错误信息
原理说明部分重复解决方案内容，未解释底层机制
代码块未添加语言标识
标题过于宽泛（如“修复TypeScript错误”），未具体化（如“修复第三方类型的TypeScript模块扩充问题”）
Slug与目录名称不一致
正文长度超过300行
将实际为
```
fix
```
类型的内容标记为
```
pattern
```
（pattern适用于可复用架构，而非bug修复）