Artifacts: Creating and Managing

Artifacts: Creating and Managing

Table of Contents

1. Quick Start
2. Triggers
3. Purpose
4. When to Use Artifacts
5. Directory Structure
6. File Naming Conventions
7. Core Rules
8. Category Definitions
9. Helper Scripts
10. Integration Pattern
11. Supporting Files
12. Best Practices
13. Red Flags to Avoid

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.

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"

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.

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)

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)

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

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

Core Rules

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

Category Definitions

Research

Purpose: Investigate libraries, tools, or approaches

Template: See templates/​research_template.md

Example usage: "Research GraphQL client libraries for React"

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"

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"

Plans

Purpose: Document implementation approach

Template: See templates/​implementation_plan_template.md

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

ADRs (Architecture Decision Records)

Purpose: Document architectural decisions

Template: See templates/​adr_template.md

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

Helper Scripts

All scripts located in .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

create_research_topic.py

See scripts/​create_research_topic.py for full script.

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

create_spike.py

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

create_analysis.py

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

create_implementation_plan.py

See scripts/​create_implementation_plan.py for full script.

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

Integration Pattern

Typical workflow:

1. Create artifact: Use helper scripts (see Helper Scripts section)
2. Work on artifact:
   • Add findings, analysis, or decisions
   • Reference code, documentation, or other artifacts
   • Update as investigation progresses
3. Complete artifact:
   • Mark as complete (status: accepted/​completed)
   • Move to completed/ if ADR
   • Reference in code or documentation
   • Archive or delete if temporary
4. 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

Usage Examples

See examples/ directory for detailed usage examples including:

• Research library workflow
• ADR creation workflow
• Implementation plan workflow

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

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/)

Best Practices

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

Red Flags to Avoid

1. Creating artifacts in wrong location - Always use .claude/​artifacts/
2. Skipping date folder - All artifacts under YYYY-MM-DD/
3. Mixed case names - Use kebab-case consistently
4. No category folder - Put in research/, spikes/, etc.
5. Creating without template - Use helper scripts
6. Leaving artifacts incomplete - Finish or delete
7. Not archiving ADRs - Move completed ADRs to completed/
8. 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.