Work-context documentation section and linear-beads integration¶
- Date: 2026-06-03
- Status: Accepted
- Tags:
structuretooling
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 fileswork/patterns/— three usage pattern fileswork/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 theskip-adrPR label
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.