The TL;DR

  1. Be explicit — Say what you want: summarize, respond, open a PR, etc.
  2. Give context — Reference files, functions, or packages directly.
  3. Ask questions — Let Charlie help define unclear specs or tradeoffs.
Heads-up: Need to stop Charlie mid-run? There’s no stop button yet, but you can find current workarounds in the Troubleshooting guide -> How to stop Charlie.

​
How to converse with Charlie

Charlie works best when instructions are clear, contextual, and purposeful.

​
Be explicit with the action

Say exactly what you want Charlie to do. Examples:

@CharlieHelps open a PR that adds tests for edge cases in …

@CharlieHelps leave a comment diagnosing this bug

@CharlieHelps make a commit to change the …

​
Include relevant context

Reference specific code locations, especially when asking for a change:

@CharlieHelps in @acmeco/core, add a new function that…

@CharlieHelps in ./lib/user/getUserName.ts, fix the fallback logic to use…

​
State intent and constraints

If something must or must not be done, call it out directly:

@CharlieHelps ensure the function handles null values and does not mutate global state.

​
Clarify the Spec

Converse with Charlie to think through problems before jumping to solutions. This helps uncover potential gaps or ambiguities in your spec.

@CharlieHelps review the spec of this issue and list 2-3 clarification questions.

@CharlieHelps before coding, what part of the spec seems undefined or ambiguous?

​
Propose Implementation Plans

Treat Charlie like a teammate you’re planning with:

@CharlieHelps suggest two implementation approaches and explain tradeoffs.

@CharlieHelps compare functional vs class-based implementation here.
Then, cherry pick the ideas you like most, discuss tradeoffs with Charlie, and refine the plan iteratively.

​
Repository Hygiene

Charlie performs best in a clean and well-documented codebase. These practices reduce ambiguity and increase the quality of automated work:

Keep READMEs up-to-date

Include behaviors, edge cases, and usage examples.

Document your functions and types

Using JSDocs or other comments to explain your code clearly.

Maintain reliable CI

Setup check commands and make sure they are fast and stable.

Remove unused code with knip

Use knip to remove dead code and unused packages.

Keep instructions current

Keep your instruction file(s) up-to-date with your engineering best practices and example usage.

Configuring GitHub autolinks to reference external resources

Setup GitHub Autolinks for improved Linear issue connection