Skip to content

Work-context documentation section and linear-beads integration

  • Date: 2026-06-03
  • Status: Accepted
  • Tags: structure tooling

Context

The 2026-06-03 Claude Code insights report (work laptop, 215 sessions over 21 days) surfaced three categories of reusable material: CLAUDE.md snippets that prevent recurring devops friction, usage patterns validated across infrastructure sessions, and guidance for three Claude Code features relevant to the devops workflow.

Additionally, linear-beads (https://github.com/nikvdp/linear-beads) was identified as a useful complement to the Linear MCP plugin — a CLI-first, agent-friendly interface to Linear with offline support.

All of this is professional/devops-context material: too specific to belong in claude/patterns/ alongside general patterns, but reusable enough to warrant permanent documentation. A dedicated top-level section provides a clear home for work-context content that scales to future insights reports.

Decision

Introduce a work/ top-level directory as a dedicated home for professional-context AI tooling content extracted from insights reports. The initial population is:

  • work/claude-md-snippets/ — five CLAUDE.md snippet files
  • work/patterns/ — three usage pattern files
  • work/feature-guidance/ — three Claude Code feature guidance files

Add linear/linear-beads.md as a reference doc for the linear-beads CLI, cross-referenced from linear/README.md.

Alternatives Considered

Option Why Rejected
claude/patterns/devops/ subdirectory Buries devops-specific content inside the Claude section; doesn't establish a first-class home for professional-context material
Scatter across existing directories with devops-tagged filenames Mixes general and context-specific patterns; makes future reports harder to organise

Consequences

Positive:

  • work/ is now the canonical home for content extracted from future CC insights reports
  • CLAUDE.md snippets are documented with friction context, making them easier to evaluate and adopt selectively
  • linear-beads is documented alongside the Linear MCP plugin for easy comparison

Negative / Trade-offs:

  • New top-level directory adds to the repo surface area
  • Content in work/ is more perishable than general patterns — devops conventions change as the infrastructure stack evolves

Ongoing obligations:

  • When new insights reports are processed, check work/ for stale content
  • Any new file added to work/ requires either a new ADR or the skip-adr PR label

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.