|
| 1 | +--- |
| 2 | +title: "Scope Keys: How Context Inheritance Works" |
| 3 | +description: "Understanding how Codegen groups related interactions and inherits context across conversations" |
| 4 | +--- |
| 5 | + |
| 6 | +# Scope Keys: How Context Inheritance Works |
| 7 | + |
| 8 | +Scope keys are Codegen's way of grouping related agent runs together so that context can be inherited between interactions. Think of them as conversation threads that help Codegen understand when different requests are part of the same ongoing work. |
| 9 | + |
| 10 | +## What Are Scope Keys? |
| 11 | + |
| 12 | +A scope key is a unique identifier that groups related agent interactions. When you interact with Codegen multiple times in the same "scope," each new interaction can build on the context and work from previous interactions in that scope. |
| 13 | + |
| 14 | +This enables powerful workflows like: |
| 15 | +- Continuing conversations in the same Slack thread |
| 16 | +- Building on previous work in the same Linear ticket |
| 17 | +- Adding commits to existing PRs instead of creating new ones |
| 18 | +- Maintaining context across multiple requests |
| 19 | + |
| 20 | +## How Scope Keys Work by Platform |
| 21 | + |
| 22 | +### Slack Threads |
| 23 | +**Scope Key Format:** `slack-{thread_timestamp}` |
| 24 | + |
| 25 | +When you mention Codegen in a Slack thread, all messages in that thread share the same scope key. This means: |
| 26 | +- Codegen remembers the entire conversation history |
| 27 | +- Follow-up requests build on previous work |
| 28 | +- Context from earlier messages is automatically inherited |
| 29 | + |
| 30 | +``` |
| 31 | +Thread: "Can you fix the login bug?" |
| 32 | +├── Codegen creates PR #123 |
| 33 | +└── "Please also add input validation" |
| 34 | + └── Codegen adds commits to PR #123 (same scope!) |
| 35 | +``` |
| 36 | + |
| 37 | +### Linear Issues |
| 38 | +**Scope Key Format:** `linear-{issue_id}` |
| 39 | + |
| 40 | +All work on the same Linear issue shares a scope key. This enables: |
| 41 | +- Building on previous implementations |
| 42 | +- Maintaining context across multiple comments |
| 43 | +- Continuing work where you left off |
| 44 | + |
| 45 | +``` |
| 46 | +Linear Issue CG-456: "Improve test coverage" |
| 47 | +├── Comment: "Add tests for auth module" |
| 48 | +│ └── Codegen creates PR #789 |
| 49 | +└── Comment: "Also need integration tests" |
| 50 | + └── Codegen adds to PR #789 (same scope!) |
| 51 | +``` |
| 52 | + |
| 53 | +### GitHub PRs |
| 54 | +**Scope Key Format:** `github-pr-{pr_number}-{repo_id}` |
| 55 | + |
| 56 | +Work on the same PR is grouped together, allowing: |
| 57 | +- Adding commits to existing PRs |
| 58 | +- Responding to review feedback |
| 59 | +- Iterating on the same feature branch |
| 60 | + |
| 61 | +``` |
| 62 | +PR #123: "Add user authentication" |
| 63 | +├── Initial PR created |
| 64 | +├── Review comment: "Fix the validation logic" |
| 65 | +│ └── Codegen adds fixing commit |
| 66 | +└── Review comment: "Add error handling" |
| 67 | + └── Codegen adds another commit (same PR!) |
| 68 | +``` |
| 69 | + |
| 70 | +### API Calls |
| 71 | +**Scope Key Format:** `api-{run_id}` or derived from task timeline |
| 72 | + |
| 73 | +API interactions can inherit scope from: |
| 74 | +- The task timeline if provided |
| 75 | +- Previous API calls in the same session |
| 76 | +- Falls back to unique run ID if no context |
| 77 | + |
| 78 | +## Why This Matters |
| 79 | + |
| 80 | +### ✅ With Scope Keys (Good) |
| 81 | +``` |
| 82 | +Slack Thread: |
| 83 | +You: "Create a PR to fix the login bug" |
| 84 | +Codegen: Creates PR #123 |
| 85 | +
|
| 86 | +You: "Please also add input validation" |
| 87 | +Codegen: Adds commits to PR #123 ← Same PR! |
| 88 | +
|
| 89 | +You: "The tests are failing" |
| 90 | +Codegen: Fixes tests in PR #123 ← Still same PR! |
| 91 | +``` |
| 92 | + |
| 93 | +### ❌ Without Scope Keys (Bad) |
| 94 | +``` |
| 95 | +You: "Create a PR to fix the login bug" |
| 96 | +Codegen: Creates PR #123 |
| 97 | +
|
| 98 | +You: "Please also add input validation" |
| 99 | +Codegen: Creates PR #124 ← New PR! 😞 |
| 100 | +
|
| 101 | +You: "The tests are failing" |
| 102 | +Codegen: Creates PR #125 ← Another new PR! 😞 |
| 103 | +``` |
| 104 | + |
| 105 | +## Best Practices |
| 106 | + |
| 107 | +### Do This ✅ |
| 108 | +- **Continue conversations in the same thread/ticket** - This ensures context is inherited |
| 109 | +- **Ask for changes in the same scope** - Codegen will update existing work |
| 110 | +- **Reference previous work** - Codegen can build on what it already knows |
| 111 | + |
| 112 | +### Avoid This ❌ |
| 113 | +- **Starting new threads for related work** - Context gets lost |
| 114 | +- **Creating new tickets for follow-ups** - Breaks the scope chain |
| 115 | +- **Asking for "new PRs" unnecessarily** - Usually you want to update existing work |
| 116 | + |
| 117 | +## Technical Implementation |
| 118 | + |
| 119 | +Scope keys are implemented in the agent runner system: |
| 120 | + |
| 121 | +```python |
| 122 | +# Each platform implements scope key generation |
| 123 | +class SlackRunner: |
| 124 | + def agent_run_scope_key(self) -> str: |
| 125 | + return f"slack-{self.slack_thread_ts}" |
| 126 | + |
| 127 | +class LinearRunner: |
| 128 | + def agent_run_scope_key(self) -> str: |
| 129 | + return f"linear-{self.linear_issue_id}" |
| 130 | + |
| 131 | +class GithubRunner: |
| 132 | + def agent_run_scope_key(self) -> str: |
| 133 | + return f"github-pr-{self.pr_number}-{self.repo_id}" |
| 134 | +``` |
| 135 | + |
| 136 | +When a new agent run starts, the system: |
| 137 | +1. Generates the appropriate scope key |
| 138 | +2. Looks up previous runs with the same scope key |
| 139 | +3. Inherits context from those previous runs |
| 140 | +4. Continues the work in the same "conversation" |
| 141 | + |
| 142 | +## Troubleshooting |
| 143 | + |
| 144 | +**Problem:** Codegen keeps creating new PRs instead of updating existing ones |
| 145 | +**Solution:** Make sure you're asking for changes in the same Slack thread, Linear issue, or PR where the original work was done. |
| 146 | + |
| 147 | +**Problem:** Codegen doesn't remember previous context |
| 148 | +**Solution:** Check that you're interacting in the same scope (same thread/ticket/PR) as the previous interaction. |
| 149 | + |
| 150 | +**Problem:** Context seems to be inherited from unrelated work |
| 151 | +**Solution:** This might indicate a scope key collision - check that you're working in the right thread/ticket/PR. |
| 152 | + |
| 153 | +--- |
| 154 | + |
| 155 | +Understanding scope keys helps you work more effectively with Codegen by ensuring your requests build on each other rather than starting from scratch each time. |
| 156 | + |
![codegen-sh[bot]](https://avatars.githubusercontent.com/in/321279?v=4&size=40){kind=avatar}
0 commit comments