artifacts-creating-and-managing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Artifacts: Creating and Managing

工件：创建与管理

Quick Start

快速开始

See scripts/create_adr.py for creating ADRs.

See scripts/create_research_topic.py for creating research topics.

See scripts/create_implementation_plan.py for creating implementation plans.

创建ADR请参考scripts/create_adr.py。

创建研究主题请参考scripts/create_research_topic.py。

创建实施计划请参考scripts/create_implementation_plan.py。

Triggers

触发方式

Trigger with phrases like:

"create an ADR"
"create ADR for [decision]"
"research [topic]"
"create research topic"
"spike investigation on [topic]"
"create spike for [investigation]"
"implementation plan for [feature]"
"create analysis"
"analyze [subject]"
"document decision"
"plan implementation"

使用以下短语触发：

"create an ADR"
"create ADR for [decision]"
"research [topic]"
"create research topic"
"spike investigation on [topic]"
"create spike for [investigation]"
"implementation plan for [feature]"
"create analysis"
"analyze [subject]"
"document decision"
"plan implementation"

Purpose

用途

Standardizes how artifacts are created and organized within

.claude/artifacts/

directory. Artifacts are temporary work products that support development but don't belong in version control or permanent documentation.

标准化.claude/artifacts/目录下工件的创建与管理方式。工件是支持开发工作的临时产物，不属于版本控制或永久文档范畴。

When to Use This Skill

何时使用本技能

Use when asked to:

Document architectural decisions ("create an ADR for event sourcing")
Research technical topics ("research GraphQL libraries for React")
Plan feature implementations ("create implementation plan for 2FA")
Conduct time-boxed investigations ("spike on OAuth2 integration")
Analyze existing code or architecture ("analyze performance bottlenecks")

Do NOT use when:

Creating permanent documentation (use
```
docs/
```
directory instead)
Writing source code (use
```
src/
```
directory)
User needs quick inline answers (respond directly in conversation)

当需要以下操作时使用：

记录架构决策（如“为事件溯源创建ADR”）
研究技术主题（如“研究适用于React的GraphQL库”）
规划功能实施（如“创建双因素认证的实施计划”）
开展限时技术调研（如“调研OAuth2集成”）
分析现有代码或架构（如“分析性能瓶颈”）

请勿在以下场景使用：

创建永久文档（请使用docs/目录）
编写源代码（请使用src/目录）
用户需要快速即时回答（直接在对话中回复）

When to Use Artifacts

何时使用工件

Use artifacts when:

Conducting research ("research GraphQL libraries")
Creating spikes ("spike on authentication approaches")
Writing analysis ("analyze performance bottlenecks")
Documenting decisions (ADRs)
Planning implementations
Capturing session notes
Recording investigation results

Don't use artifacts for:

Permanent documentation (use
```
docs/
```
instead)
Source code (use
```
src/
```
instead)
Tests (use
```
tests/
```
instead)
Configuration (use config files)

使用工件的场景：

开展研究（如“研究GraphQL库”）
进行技术探索（spikes，如“调研认证方案”）
撰写分析文档（如“分析性能瓶颈”）
记录决策（ADRs）
规划实施
记录会议纪要
保存调研结果

请勿使用工件的场景：

永久文档（请使用docs/目录）
源代码（请使用src/目录）
测试用例（请使用tests/目录）
配置文件（请使用对应配置文件）

Directory Structure

目录结构

.claude/artifacts/
├── YYYY-MM-DD/                    # Date-based organization
│   ├── research/                  # Research topics
│   │   └── topic-name.md
│   ├── spikes/                    # Technical spikes
│   │   └── spike-name.md
│   ├── analysis/                  # Code/architecture analysis
│   │   └── analysis-name.md
│   ├── plans/                     # Implementation plans
│   │   └── plan-name.md
│   ├── sessions/                  # Session notes
│   │   └── session-name.md
│   └── adr/                       # Architecture Decision Records
│       └── NNN-decision-name.md
└── completed/                     # Archived artifacts
    └── adr/
        └── NNN-decision-name.md

.claude/artifacts/
├── YYYY-MM-DD/                    # 按日期组织
│   ├── research/                  # 研究主题
│   │   └── topic-name.md
│   ├── spikes/                    # 技术探索
│   │   └── spike-name.md
│   ├── analysis/                  # 代码/架构分析
│   │   └── analysis-name.md
│   ├── plans/                     # 实施计划
│   │   └── plan-name.md
│   ├── sessions/                  # 会议纪要
│   │   └── session-name.md
│   └── adr/                       # 架构决策记录
│       └── NNN-decision-name.md
└── completed/                     # 已归档工件
    └── adr/
        └── NNN-decision-name.md

File Naming Conventions

文件命名规范

Research topics:

.claude/artifacts/YYYY-MM-DD/research/topic-name.md
Example: .claude/artifacts/2025-12-24/research/graphql-libraries.md

Spikes:

.claude/artifacts/YYYY-MM-DD/spikes/spike-name.md
Example: .claude/artifacts/2025-12-24/spikes/oauth2-integration.md

Analysis:

.claude/artifacts/YYYY-MM-DD/analysis/analysis-name.md
Example: .claude/artifacts/2025-12-24/analysis/performance-bottlenecks.md

Implementation plans:

.claude/artifacts/YYYY-MM-DD/plans/feature-name-plan.md
Example: .claude/artifacts/2025-12-24/plans/user-authentication-plan.md

ADRs:

.claude/artifacts/YYYY-MM-DD/adr/NNN-decision-title.md
Example: .claude/artifacts/2025-12-24/adr/001-use-event-sourcing.md

研究主题：

.claude/artifacts/YYYY-MM-DD/research/topic-name.md
示例：.claude/artifacts/2025-12-24/research/graphql-libraries.md

技术探索（spikes）：

.claude/artifacts/YYYY-MM-DD/spikes/spike-name.md
示例：.claude/artifacts/2025-12-24/spikes/oauth2-integration.md

分析文档：

.claude/artifacts/YYYY-MM-DD/analysis/analysis-name.md
示例：.claude/artifacts/2025-12-24/analysis/performance-bottlenecks.md

实施计划：

.claude/artifacts/YYYY-MM-DD/plans/feature-name-plan.md
示例：.claude/artifacts/2025-12-24/plans/user-authentication-plan.md

ADRs：

.claude/artifacts/YYYY-MM-DD/adr/NNN-decision-title.md
示例：.claude/artifacts/2025-12-24/adr/001-use-event-sourcing.md

Core Rules

核心规则

Date-based organization - All artifacts under
```
YYYY-MM-DD/
```
directory
Kebab-case names - Use hyphens, lowercase, no spaces
Category folders - research/, spikes/, analysis/, plans/, adr/
Markdown format - All artifacts are .md files
Templated creation - Use helper scripts for consistency
Completion tracking - Move to
```
completed/
```
when done

按日期组织 - 所有工件置于YYYY-MM-DD/目录下
短横线命名法（kebab-case） - 使用连字符、小写字母，无空格
分类文件夹 - research/、spikes/、analysis/、plans/、adr/
Markdown格式 - 所有工件均为.md文件
模板化创建 - 使用辅助脚本确保一致性
完成追踪 - 完成后移至completed/目录

Category Definitions

分类定义

Research

研究

Purpose: Investigate libraries, tools, or approaches

Template: See templates/research_template.md

Example usage: "Research GraphQL client libraries for React"

用途： 调研库、工具或方案

模板： 参考templates/research_template.md

示例用法： "研究适用于React的GraphQL客户端库"

Spikes

技术探索（Spikes）

Purpose: Time-boxed technical investigation

Template: Spike template not yet created (use research template as starting point)

Example usage: "Spike on OAuth2 integration with existing auth system"

用途： 限时技术调研

模板： 暂未创建Spike模板（可使用研究模板作为起点）

示例用法： "调研OAuth2与现有认证系统的集成"

Analysis

分析

Purpose: Investigate existing code/architecture

Template: Analysis template not yet created (use research template as starting point)

Example usage: "Analyze performance bottlenecks in API handlers"

用途： 调研现有代码/架构

模板： 暂未创建分析模板（可使用研究模板作为起点）

示例用法： "分析API处理器的性能瓶颈"

Plans

计划

Purpose: Document implementation approach

Template: See templates/implementation_plan_template.md

Example usage: "Plan implementation of two-factor authentication"

用途： 记录实施方案

模板： 参考templates/implementation_plan_template.md

示例用法： "规划双因素认证的实施"

ADRs (Architecture Decision Records)

ADRs（架构决策记录）

Purpose: Document architectural decisions

Template: See templates/adr_template.md

Example usage: "ADR 001: Use Event Sourcing for Audit Trail"

用途： 记录架构决策

模板： 参考templates/adr_template.md

示例用法： "ADR 001：使用事件溯源实现审计追踪"

Helper Scripts

辅助脚本

All scripts located in

.claude/skills/artifacts-creating-and-managing/scripts/

所有脚本位于.claude/skills/artifacts-creating-and-managing/scripts/目录下：

create_adr.py

See scripts/create_adr.py for full script.

Required: --title, --status, --context Optional: --decision, --consequences

完整脚本请参考scripts/create_adr.py。

必填参数： --title、--status、--context 可选参数： --decision、--consequences

create_research_topic.py

See scripts/create_research_topic.py for full script.

Required: --topic, --objective Optional: --questions (multiple)

完整脚本请参考scripts/create_research_topic.py。

必填参数： --topic、--objective 可选参数： --questions（可多个）

create_spike.py

Note: Spike script not yet created. Use create_research_topic.py as alternative.

注意：暂未创建Spike脚本。可使用create_research_topic.py作为替代。

create_analysis.py

Note: Analysis script not yet created. Use create_research_topic.py as alternative.

注意：暂未创建分析脚本。可使用create_research_topic.py作为替代。

create_implementation_plan.py

See scripts/create_implementation_plan.py for full script.

Required: --feature, --overview Optional: --steps (multiple), --risks

完整脚本请参考scripts/create_implementation_plan.py。

必填参数： --feature、--overview 可选参数： --steps（可多个）、--risks

Integration Pattern

集成模式

Typical workflow:

Create artifact: Use helper scripts (see Helper Scripts section)
Work on artifact:
- Add findings, analysis, or decisions
- Reference code, documentation, or other artifacts
- Update as investigation progresses
Complete artifact:
- Mark as complete (status: accepted/completed)
- Move to
```
completed/
```
  if ADR
- Reference in code or documentation
- Archive or delete if temporary
Cross-reference:
- Link from code comments:
```
// See: .claude/artifacts/YYYY-MM-DD/research/topic.md
```
- Link from documentation:
```
docs/
```
  references artifacts
- Link between artifacts: Related ADRs reference each other

典型工作流：

创建工件： 使用辅助脚本（参考辅助脚本章节）
处理工件：
- 添加研究结果、分析或决策
- 引用代码、文档或其他工件
- 随调研进展更新内容
完成工件：
- 标记为完成（状态：已接受/已完成）
- 若为ADR则移至completed/目录
- 在代码或文档中引用
- 若为临时工件则归档或删除
交叉引用：
- 代码注释中链接：
```
// 参考：.claude/artifacts/YYYY-MM-DD/research/topic.md
```
- 文档中链接：docs/引用工件
- 工件间链接：相关ADRs互相引用

Usage Examples

使用示例

See examples/ directory for detailed usage examples including:

Research library workflow
ADR creation workflow
Implementation plan workflow

详细使用示例请参考examples/目录，包括：

库研究工作流
ADR创建工作流
实施计划工作流

Expected Outcomes

预期成果

Successful Artifact Creation:

Artifact created in correct location (

.claude/artifacts/YYYY-MM-DD/{category}/

)

File follows naming conventions (kebab-case)
Template applied with placeholders filled
Ready for content addition

Completed Artifact:

Decision documented (for ADRs)
Research findings captured (for research)
Implementation steps defined (for plans)
Cross-referenced in code/docs where appropriate
Moved to
```
completed/
```
if applicable

成功创建工件：

工件创建于正确位置（

.claude/artifacts/YYYY-MM-DD/{category}/

）

文件遵循命名规范（kebab-case）
已应用模板并填充占位符
可随时添加内容

完成的工件：

已记录决策（针对ADRs）
已捕获研究结果（针对研究类）
已定义实施步骤（针对计划类）
在代码/文档中进行了适当的交叉引用
已移至completed/目录（如适用）

Supporting Files

支持文件

templates/ - Markdown templates:
- adr-template.md
- research-template.md
- spike-template.md
- analysis-template.md
- plan-template.md
scripts/ - Helper scripts:
- create_adr.py
- create_research_topic.py
- create_spike.py
- create_analysis.py
- create_implementation_plan.py
- list_artifacts.py (find all artifacts)
- archive_artifact.py (move to completed/)

templates/ - Markdown模板：
- adr-template.md
- research-template.md
- spike-template.md
- analysis-template.md
- plan-template.md
scripts/ - 辅助脚本：
- create_adr.py
- create_research_topic.py
- create_spike.py
- create_analysis.py
- create_implementation_plan.py
- list_artifacts.py（查找所有工件）
- archive_artifact.py（移至completed/目录）

Best Practices

最佳实践

Use templates - Scripts ensure consistency
Date organization - Easy to find recent artifacts
Descriptive names - Clear purpose from filename
Complete artifacts - Don't leave them half-finished
Cross-reference - Link artifacts to code/docs
Archive when done - Move completed ADRs to
```
completed/
```
Delete temporary artifacts - Don't accumulate unnecessary files
Update status - Keep artifact status current

使用模板 - 脚本确保一致性
按日期组织 - 便于查找近期工件
描述性命名 - 文件名清晰体现用途
完成工件 - 不要半途而废
交叉引用 - 在代码/文档中链接工件
完成后归档 - 将已完成的ADRs移至completed/目录
删除临时工件 - 不要堆积不必要的文件
更新状态 - 保持工件状态为最新

Red Flags to Avoid

需避免的常见问题

Creating artifacts in wrong location - Always use
```
.claude/artifacts/
```
Skipping date folder - All artifacts under
```
YYYY-MM-DD/
```
Mixed case names - Use kebab-case consistently
No category folder - Put in research/, spikes/, etc.
Creating without template - Use helper scripts
Leaving artifacts incomplete - Finish or delete
Not archiving ADRs - Move completed ADRs to
```
completed/
```
Creating permanent docs as artifacts - Use
```
docs/
```
for permanent documentation

Key principle: Artifacts are temporary work products with standardized structure. They support development but aren't permanent documentation.

Remember: Use helper scripts for consistency, organize by date, and archive/delete when complete.

在错误位置创建工件 - 务必使用.claude/artifacts/目录
跳过日期文件夹 - 所有工件必须置于YYYY-MM-DD/目录下
混合大小写命名 - 统一使用kebab-case
未放入分类文件夹 - 必须放入research/、spikes/等对应目录
不使用模板创建 - 请使用辅助脚本
工件未完成 - 完成或删除
未归档ADRs - 将已完成的ADRs移至completed/目录
将永久文档作为工件创建 - 永久文档请使用docs/目录

核心原则： 工件是具有标准化结构的临时工作产物，用于支持开发但不属于永久文档。

注意： 使用辅助脚本确保一致性，按日期组织，完成后归档或删除。

artifacts-creating-and-managing

Original

Translation

Artifacts: Creating and Managing

工件：创建与管理

Table of Contents

目录

Quick Start

快速开始

Triggers

触发方式

Purpose

用途

When to Use This Skill

何时使用本技能

When to Use Artifacts

何时使用工件

Directory Structure

目录结构

File Naming Conventions

文件命名规范

Core Rules

核心规则

Category Definitions

分类定义

Research

研究

Spikes

技术探索（Spikes）

Analysis

分析

Plans

计划

ADRs (Architecture Decision Records)

ADRs（架构决策记录）

Helper Scripts

辅助脚本

create_adr.py

create_adr.py

create_research_topic.py

create_research_topic.py

create_spike.py

create_spike.py

create_analysis.py

create_analysis.py

create_implementation_plan.py

create_implementation_plan.py

Integration Pattern

集成模式

Usage Examples

使用示例

Expected Outcomes

预期成果

Supporting Files

支持文件

Best Practices

最佳实践

Red Flags to Avoid

需避免的常见问题