--- title: "Give Claude Code your Linear sprint and decision context in Markdown" description: "Export Linear workspace structure, the current sprint, backlog priorities, and technical decisions to Markdown, so Claude Code plans and reports in context." canonical: "https://scalewithsearch.com/articles/claude-code-with-linear" date: "2026-01-28" modified: "2026-09-25" --- ## Site navigation - [Scale With Search](https://scalewithsearch.com/) - Real estate - Real estate - [Real estate](https://scalewithsearch.com/for/real-estate) - Work - Start here - [Send your brief](https://scalewithsearch.com/work#send-your-brief) - [Prepare your six-question brief](https://scalewithsearch.com/work#prepare-your-six-question-brief) - Build - [Site build, content library with SEO, signal desk](https://scalewithsearch.com/work) - For your business - Trades and home services - [Auto body and collision shops](https://scalewithsearch.com/for/auto-body-and-collision-shops) - [Foundation and home repair contractors](https://scalewithsearch.com/for/foundation-and-home-repair) - [Garage door and fencing contractors](https://scalewithsearch.com/for/garage-door-and-fencing-contractors) - [HVAC contractors](https://scalewithsearch.com/for/hvac-contractors) - [Janitorial and commercial cleaning companies](https://scalewithsearch.com/for/janitorial-and-commercial-cleaning) - [Locksmiths](https://scalewithsearch.com/for/locksmiths) - [Moving companies](https://scalewithsearch.com/for/moving-companies) - [Pest control companies](https://scalewithsearch.com/for/pest-control-companies) - [Plumbing and electrical contractors](https://scalewithsearch.com/for/plumbing-and-electrical-contractors) - [Restoration and water or fire damage companies](https://scalewithsearch.com/for/restoration-and-water-fire-damage) - [Roofing companies](https://scalewithsearch.com/for/roofing-companies) - [Towing companies](https://scalewithsearch.com/for/towing-companies) - [Tree services and landscaping companies](https://scalewithsearch.com/for/tree-services-and-landscaping) - [Solar installers](https://scalewithsearch.com/for/solar-installation) - [General contractors](https://scalewithsearch.com/for/general-contractors-and-construction) - [Paving, concrete, and flooring contractors](https://scalewithsearch.com/for/paving) - Practices and professional services - [Bookkeeping and tax practices](https://scalewithsearch.com/for/bookkeeping-and-tax-practices) - [Dental practices](https://scalewithsearch.com/for/dental-practices) - [Family and criminal defense law firms](https://scalewithsearch.com/for/family-and-criminal-defense-law-firms) - [Med spas and aesthetics practices](https://scalewithsearch.com/for/med-spas-and-aesthetics) - [Personal injury law firms](https://scalewithsearch.com/for/personal-injury-law-firms) - [Veterinary clinics](https://scalewithsearch.com/for/veterinary-clinics) - [Gyms and fitness studios](https://scalewithsearch.com/for/fitness) - [Therapy and outpatient health practices](https://scalewithsearch.com/for/therapy-and-outpatient-health) - [Medical billing companies](https://scalewithsearch.com/for/medical-billing) - [Insurance agencies](https://scalewithsearch.com/for/insurance-agencies) - [Financial advisors](https://scalewithsearch.com/for/financial-advisors) - [Property management companies](https://scalewithsearch.com/for/property-management) - [Recruiting and staffing agencies](https://scalewithsearch.com/for/recruiting-and-staffing) - [Architects and interior designers](https://scalewithsearch.com/for/architects-and-interior-designers) - [Logistics and supply chain companies](https://scalewithsearch.com/for/logistics-and-supply-chain) - Agencies, MSPs, and manufacturing - [IT and managed service providers](https://scalewithsearch.com/for/it-and-managed-service-providers) - [Machine shops and precision manufacturers](https://scalewithsearch.com/for/machine-shops-and-precision-manufacturing) - [Marketing agencies and freelancers](https://scalewithsearch.com/for/marketing-agencies-and-freelancers) - [SEO agencies and consultants](https://scalewithsearch.com/for/seo-agencies-and-consultants) - [Small manufacturers and fabricators](https://scalewithsearch.com/for/small-manufacturers-and-fabricators) - Restaurants, shops, studios, and nonprofits - [Restaurants and hospitality businesses](https://scalewithsearch.com/for/restaurants-and-hospitality) - [Retail stores and ecommerce sellers](https://scalewithsearch.com/for/retail-and-ecommerce) - [Photographers, event planners, and travel agents](https://scalewithsearch.com/for/photographers) - [Churches and nonprofits](https://scalewithsearch.com/for/churches-and-nonprofits) - [All industries](https://scalewithsearch.com/for/) - Learn - For your office - [Office job guides](https://scalewithsearch.com/guides/) - [Browser calculators](https://scalewithsearch.com/tools/) - Start here - [How it works](https://scalewithsearch.com/how-it-works) - [Free Starter Kit](https://scalewithsearch.com/kit/business-memory-starter-kit.zip) - [Synthetic specimen](https://scalewithsearch.com/specimen/working-session-specimen.zip) - Guides - [The Complete Guide to Business Memory for AI Agents](https://scalewithsearch.com/articles/business-memory-for-ai-agents-guide) - [The Complete Small-Business Guide to AI Agent Governance](https://scalewithsearch.com/articles/ai-agent-governance-guide-small-business) - [The Complete Guide to Leaving Vendor AI Memory](https://scalewithsearch.com/articles/leaving-vendor-ai-memory-guide) - Articles by cluster - [Business memory](https://scalewithsearch.com/articles/business-memory-for-ai-agents-guide) - [Agent governance](https://scalewithsearch.com/articles/ai-agent-governance-guide-small-business) - [Migration and ownership](https://scalewithsearch.com/articles/leaving-vendor-ai-memory-guide) - For machines - [llms.txt](https://scalewithsearch.com/llms.txt) - [llms-full.txt](https://scalewithsearch.com/llms-full.txt) - [Machine view](https://scalewithsearch.com/?view=machine) - Company - Evidence - [Proof](https://scalewithsearch.com/proof) - Company - [About](https://scalewithsearch.com/about) # Give Claude Code your Linear sprint and decision context in Markdown. Linear tracks your development work: the issue backlog, sprint plans, feature priorities, and team capacity. It holds the context that explains what you are building and why. Claude Code cannot see it. When you ask for help with sprint planning, a project update, or a technical decision, you explain context that already exists in Linear. You describe issue states. You list sprint goals. You explain why a feature won priority. You paste issue descriptions. You build software with AI, and the AI does not know what you are building. This article builds a Markdown context layer that gives Claude Code your Linear context without a live integration. ## Know what Claude Code is missing Linear organizes the development process. It does not explain your project to an outside AI. Without a context layer, Claude Code does not know: - which features are in the current sprint; - why you chose them over other backlog items; - how your team defines "In Progress" and "In Review"; - which issues are blocked, and why; - your team's velocity and capacity; - how epics, issues, and sub-tasks relate; - the technical decisions recorded in issue comments. Linear shows all of this in its interface, and it stays there. You become the translator between the tracker and the assistant. ## Build the bridge in six steps 1. Export the project structure: teams, projects, and workflow states. 2. Export the active work: the current sprint, backlog priorities, and blocked issues. 3. Export the key decisions from issue comments. 4. Store the exports as Markdown files in an Obsidian vault. 5. Write a `CLAUDE.md` that explains your development process. 6. Start Claude Code in the vault, so it reads the project context. Linear stays the source of truth. The vault becomes Claude Code's project memory. You update it by hand when the context changes. Linear also offers an API, and MCP servers can connect it to Claude Code. A live connection needs a scoped token and a rule about which actions the agent may take on issues. The export route needs no credentials and changes nothing in Linear, so it is the safer first step. ## Choose what to export A Linear workspace can hold thousands of issues. Export the context Claude Code needs for current work and past decisions: | Export | Contents | |---|---| | Project structure | Teams, projects, workflow states, labels | | Current sprint | Active issues, assignees, progress | | Backlog priorities | The top 20 issues and why each one ranks where it does | | Epic definitions | Major features, their scope, and status | | Blocked issues | What is stuck, and why | | Technical decisions | Architecture choices, trade-offs, and the comment discussion | | Team velocity | Sprint completion rates over time | Focus on active context and reference data, not the complete history. ## Document the workspace structure Your Linear workspace has its own logic. Record the team names and focus areas, the project names and purposes, the workflow states, the label set, and the priority levels: ``` --- workspace: Acme Software last-updated: 2026-01-28 --- # Linear Workspace Structure ## Teams ### Engineering **Focus:** Core product development **Members:** 8 engineers **Projects:** Web App, Mobile App, API ### Design **Focus:** UI/UX for all products **Members:** 3 designers **Projects:** Design System, User Research ## Workflow States - **Backlog**: Not yet prioritized - **Todo**: Prioritized for upcoming work - **In Progress**: Actively being worked on - **In Review**: Code written, awaiting review - **Done**: Completed and deployed - **Canceled**: Decided not to pursue ## Priority Levels - **Urgent**: Blocking production, security issues - **High**: Key features for current quarter - **Medium**: Important but not time-sensitive - **Low**: Nice-to-have improvements ## Labels - `bug`: Something broken - `feature`: New functionality - `improvement`: Enhancement to existing feature - `tech-debt`: Code quality, refactoring - `customer-request`: Came from customer feedback ``` The structure file lets Claude Code read your organization without seeing every issue. ## Export the current sprint The active sprint is the most important context. In Linear, filter for the current cycle. Copy or export the issues into a Markdown table, and add the goal, capacity, and blockers: ``` ## Current Sprint: Jan 22-Feb 5, 2026 **Goal:** Ship payment integrations and improve dashboard performance | ID | Title | Assignee | Status | Priority | Labels | |----|-------|----------|--------|----------|--------| | ENG-234 | Add Stripe payment integration | Engineer A | In Progress | High | feature, customer-request | | ENG-235 | Optimize dashboard query performance | Engineer B | In Review | High | improvement, tech-debt | | ENG-236 | Fix mobile nav bug on iOS | Engineer C | Done | Urgent | bug | | ENG-237 | Add CSV export for reports | Engineer D | Todo | Medium | feature | **Capacity:** 8 engineers × 8 days = 64 dev-days **Committed:** 48 dev-days **Completed:** 12 dev-days (25%) **Blockers:** - ENG-234 blocked on Stripe API keys (waiting for DevOps) ``` Update the file at the start of each sprint and after each standup that changes status. ## Export the backlog priorities with reasons The backlog holds future work. Export the top priorities, and record why each one matters: ``` ## Backlog Priorities (Top 20) Updated: 2026-01-28 ### Tier 1 (Next Sprint) **ENG-240: Multi-user account support** - Priority: High - Why: 12 enterprise customers requesting it; blocks their account expansion deals - Estimate: 13 points - Dependencies: None **ENG-241: Email notification system** - Priority: High - Why: Top feature request (47 votes), core to product experience - Estimate: 8 points - Dependencies: Email service provider decision ### Tier 2 (This Quarter) **ENG-245: Dark mode** - Priority: Medium - Why: Nice-to-have, 23 customer requests - Estimate: 5 points - Dependencies: Design system updates ``` The "Why" line is the part Linear rarely shows in one place. It lets Claude Code explain a priority, not only list it. ## Record the technical decisions Issue comments hold architecture choices, the trade-offs considered, and the chosen approach. Export each key decision thread as its own file: ``` ## Technical Decision: API Architecture **Issue:** ENG-234 (Stripe integration) **Date:** 2026-01-20 **Participants:** Engineer A, Engineer B, Tech Lead ### Context Need to integrate Stripe payments. Two approaches considered: 1. Direct Stripe API calls from frontend 2. Backend proxy with our API wrapping Stripe ### Discussion **Engineer A:** Direct calls are simpler, less code on our end. **Engineer B:** But then we're exposing Stripe API keys to frontend. Security risk. Also harder to test. **Tech Lead:** Agree with Engineer B. Backend proxy gives us better control, lets us add business logic, easier to swap payment providers later if needed. ### Decision Backend proxy approach. Create `/api/payments` endpoint that wraps Stripe calls. **Tradeoffs:** - More backend code (estimated +2 days) - Better security - More flexibility for future changes - Easier testing **Implementation plan:** See ENG-234 for details ``` The file records the rejected option and its reason, not only the choice. Without the reason, a later session proposes direct frontend calls again. The [Claude Code and Cursor project memory article](/articles/claude-code-vs-cursor-project-memory) shows how to test that a fresh session finds and follows a decision file. ## Organize the vault ``` /Linear/ /Structure/ workspace-organization.md workflow-states.md team-structure.md /Active-Work/ current-sprint.md backlog-priorities.md blocked-issues.md /Epics/ payment-integrations.md dashboard-redesign.md /Decisions/ api-architecture.md tech-stack-choices.md /Metrics/ team-velocity.md cycle-completion-rates.md ``` Structure changes rarely. Active work changes each week. Decisions accumulate. Metrics change each sprint. The split lets you update each folder on its own schedule. ## Write the CLAUDE.md index `CLAUDE.md` tells Claude Code how to use the Linear files. Give it five parts: a process overview, a record map, the current focus, the priority framework, and example questions with their source files: ``` ## Development Process We work in 2-week sprints. Sprint planning on Mondays. Retrospectives on Fridays. Current sprint details: `/Linear/Active-Work/current-sprint.md` (updated weekly) ### Priority Framework Feature prioritization based on: 1. Revenue impact (blocking deals or expansion) 2. Customer request volume (votes in Linear) 3. Strategic importance (aligns with company goals) 4. Technical dependencies (what unlocks other work) See `/Linear/Active-Work/backlog-priorities.md` for current rankings. ### Workflow **Issue states:** Defined in `/Linear/Structure/workflow-states.md` **Standard flow:** Backlog → Todo → In Progress → In Review → Done **Review process:** All code reviewed by at least one other engineer before merge. ### Common Queries - "What's in the current sprint?" → Read `/Active-Work/current-sprint.md` - "What are we building next?" → Read `/Active-Work/backlog-priorities.md` - "Why did we choose this architecture?" → Search `/Decisions/` - "What's blocking progress?" → Read `/Active-Work/blocked-issues.md` ``` The query map tells Claude Code to read [only the files a question needs](/articles/what-context-should-an-agent-read), not the whole folder. ## Worked example: five jobs before and after **Sprint planning.** Before, you review Linear, estimate capacity, pick issues, and explain the context to the team. After, you ask Claude Code to help plan the next sprint. It reads the velocity file and the backlog priorities, suggests issues that fit the capacity, and explains each ranking. **Engineering update.** Before, you scan Linear, note progress, copy issue titles, and write the update. After, you ask for this week's engineering update. Claude Code reads the sprint file and drafts an update with completed work, work in progress, blockers, issue IDs, and progress figures. **Technical decision recall.** Before, the architecture discussion happened in Slack or a meeting, and the context is gone. After, you ask, "What did we decide about the API architecture?" Claude Code reads the decision file and explains the choice and its trade-offs. **Developer onboarding.** Before, you spend hours on the project structure, priorities, and workflow. After, the new developer asks Claude Code. It explains the teams, projects, workflow states, sprint goal, and backlog priorities from the files. **Feature context.** Before, you see an issue, forget why it ranks high, and search comments and Slack. After, you ask, "Why are we building multi-user accounts?" Claude Code reads the backlog file and answers: 12 enterprise customers need it, and it blocks their expansion deals. The [project manager memory article](/articles/ai-memory-for-project-managers) applies the same pattern to non-engineering projects. ## Keep the exports current **Each week,** export the sprint status: progress, completed items, and blockers. That takes about 10 minutes at standup. **Every two weeks,** refresh the backlog priorities after sprint planning, if the top 20 changed. **Each month,** update the velocity metrics, record new technical decisions, and archive completed epics. **Each quarter,** audit the structure files for workflow changes and new teams or projects. A stale sprint file does more harm than no file. If `current-sprint.md` still shows last sprint, Claude Code plans against finished work and reports blockers that someone already cleared. Add one rule to `CLAUDE.md`. The rule tells Claude Code to compare the sprint dates in the file with today's date. If the file is out of date, Claude Code says so before it plans. The date in each file heading makes that check possible. Most of the structure stays stable. You update the active work, not the whole system. The [plain-text memory article](/articles/plain-text-ai-memory) explains why dated Markdown files stay readable after the tools around them change. ## Know the limits of the export route The route is not a Linear API integration. Claude Code does not read Linear, update issues, or sync in real time. It does not replace Linear: your team still tracks work there, and the vault is Claude Code's project memory. It is not automatic: you export by hand when the context changes. Linear tracks the work. The vault gives Claude Code the memory to understand and reference it. If you are new to the tools, Claude Code installs with one terminal command, and Obsidian stores notes as plain Markdown files. You can keep Notion or Google Docs for daily work and use the vault only for agent context. ## Related: AI memory - [The Complete Guide to Leaving Vendor AI Memory](/articles/leaving-vendor-ai-memory-guide) - [How to Move Years of AI Work Out of a Vendor Archive](/articles/move-ai-work-out-of-vendor-archive) - [Replace the Model Without Rebuilding the Business Memory](/articles/replace-the-model-keep-business-memory) ---- ```text .|########||. .|########||. .|########||. |##||. .||##|. |##||. .||##|. |##||. .||##|. |#|. .|#|. |#|. .|#|. |#|. .|#|. |#| |#| |#| |#| |#| |#| .#| |#. .#| |#. .#| |#. .#. .#| .#. .#| .#. .#| |#. .#| |#. .#| |#. .#| |# ...... #| |# ...... #| |# ...... #| .# ||#########| #| .# ||#########| #| .# ||#########| #| .#. |######||######|. .#. .#. |######||######|. .#. .#. |######||######|. .#. #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# # .||####|###########################|. # # .||####|###########################|. # # .||####|###########################|. # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || #. .######|#|#########| .# #. .######|#|#########| .# #. .######|#|#########| .# .#. |#####||||#####| .#. .#. |#####||||#####| .#. .#. |#####||||#####| .#. |# ||########|| #. |# ||########|| #. |# ||########|| #. |# ...... #| |# ...... #| |# ...... #| |#. .#| |#. .#| |#. .#| |#. .#. |#. .#. |#. .#. .#| |#. .#| |#. .#| |#. |#| |#| |#| |#| |#| |#| .|#|. .|#|. .|#|. .|#|. .|#|. .|#|. |##||. .||##| |##||. .||##| |##||. .||##| .||########||. .||########||. .||########||. Scale With Search 2026 [scalewithsearch.com](https://scalewithsearch.com) ```