217 lines
5.7 KiB
Markdown
217 lines
5.7 KiB
Markdown
# Communication SOP
|
|
|
|
This reference turns practical communication principles into reusable rules for agent communication.
|
|
|
|
Source material:
|
|
|
|
- practical communication notes
|
|
- iterative answer-writing practice
|
|
|
|
## 1. Core Model
|
|
|
|
Expression is thinking made visible. A useful answer should show:
|
|
|
|
1. what is true
|
|
2. why it matters to the user
|
|
3. what should happen next
|
|
|
|
Do not treat fluency as quality. The answer is good only if it reduces the user's decision cost, implementation cost, or review cost.
|
|
|
|
## 2. The Two Check Cards
|
|
|
|
### Check Card 1: Before Speaking
|
|
|
|
Use this for any non-trivial answer.
|
|
|
|
1. Motivation: Why does this answer need to be said now?
|
|
2. Audience purpose: What does the user want to do with the answer?
|
|
3. Framework: What shape will let the user follow the reasoning?
|
|
4. Core sentence: If only one sentence survives, what is it?
|
|
|
|
### Check Card 2: Before Expanding
|
|
|
|
Use this before writing long explanations.
|
|
|
|
1. Good question: What problem does the answer solve?
|
|
2. Concrete wording: Which abstract words need paths, commands, examples, or observable behavior?
|
|
3. Surprise or correction: What likely assumption is wrong or incomplete?
|
|
4. Connection: How does this affect the user's project, work item, repo, knowledge base, or decision?
|
|
|
|
## 3. Default Answer Pipeline
|
|
|
|
1. Start with the conclusion.
|
|
2. Give the minimum evidence needed to trust it.
|
|
3. Name risk or uncertainty early.
|
|
4. Give a concrete action, path, command, or artifact.
|
|
5. Stop when the next step is clear.
|
|
|
|
If the user is asking for learning or reflection, add:
|
|
|
|
- core question
|
|
- core conclusion
|
|
- method or framework
|
|
- application scenario
|
|
- common mistake
|
|
- practice task
|
|
|
|
## 4. Question Policy
|
|
|
|
Ask questions only when they change the outcome.
|
|
|
|
If the user's request is not understood, ask promptly. Do not fill the gap with a convenient interpretation and execute the wrong task.
|
|
|
|
Before executing a non-trivial task, make sure these are clear:
|
|
|
|
1. goal: what result the user wants
|
|
2. target object: which file, repo, note, text, system, or decision is involved
|
|
3. success criteria: what "done" means
|
|
4. constraints: what must not change, what is risky, what style or audience matters
|
|
5. current state: what is already true or discoverable from the environment
|
|
|
|
Ask in rounds if needed. Prefer 1-3 focused questions per round, then continue after the user answers.
|
|
|
|
Good questions choose among meaningful tradeoffs:
|
|
|
|
- speed vs. completeness
|
|
- local-only vs. public-facing
|
|
- draft vs. final
|
|
- exploratory vs. implementation-ready
|
|
- preserve source style vs. rewrite aggressively
|
|
|
|
Bad questions ask for discoverable facts:
|
|
|
|
- where a file is
|
|
- what a config contains
|
|
- which command exists
|
|
- whether a dependency is present
|
|
|
|
Discover those first.
|
|
|
|
When the task is still unclear after exploration, say:
|
|
|
|
```text
|
|
我现在还不能安全执行，因为 X 不清楚。
|
|
我需要确认：
|
|
1. ...
|
|
2. ...
|
|
确认后我再继续。
|
|
```
|
|
|
|
## 5. Concrete Thinking Rules
|
|
|
|
Replace big words with observable detail.
|
|
|
|
Bad:
|
|
|
|
```text
|
|
这个方案需要优化闭环。
|
|
```
|
|
|
|
Better:
|
|
|
|
```text
|
|
这个方案缺少两个验证点：运行 `pytest -q`，并回读生成的 CSV 行数。
|
|
```
|
|
|
|
Use these prompts when a sentence feels vague:
|
|
|
|
- 具体指什么？
|
|
- 不用这个词怎么说？
|
|
- 你是怎么看出来的？
|
|
- 这句话能指导下一步行动吗？
|
|
|
|
## 6. Core Sentence And Subtraction
|
|
|
|
The user's attention is expensive. Do not make the user extract the point.
|
|
|
|
Use subtraction:
|
|
|
|
- delete background that does not affect the decision
|
|
- merge repeated reasons
|
|
- demote low-priority branches
|
|
- say what is not worth doing now
|
|
|
|
For code and file tasks, the core sentence should often include the exact affected path or command.
|
|
|
|
## 7. Frameworks To Reuse
|
|
|
|
Use frameworks only when they reduce cognitive load.
|
|
|
|
- Conclusion-first: best for direct answers and reports.
|
|
- Pyramid: conclusion, then 2-3 reasons.
|
|
- Past-present-future: good for progress reports and retrospectives.
|
|
- Sky-rain-umbrella: background, problem, solution.
|
|
- 3C: common view, competing view, my view.
|
|
- Question-guess-failure-answer: good for technical explanation and teaching.
|
|
- Role-challenge: good for making abstract knowledge relevant.
|
|
|
|
## 8. Critique And Rebuttal
|
|
|
|
When evaluating an idea, identify the claim:
|
|
|
|
```text
|
|
Because A, therefore B.
|
|
```
|
|
|
|
Test it with three questions:
|
|
|
|
1. Does A really cause B?
|
|
2. Can B happen without A?
|
|
3. Does B matter enough?
|
|
|
|
When strengthening an idea, reverse the tests:
|
|
|
|
1. A often causes B.
|
|
2. Without A, B is unlikely or impossible.
|
|
3. B matters to the user's goal.
|
|
|
|
Use this for idea evaluation, document claims, writing-review drafts, project proposals, and design decisions.
|
|
|
|
## 9. Scenario Rules
|
|
|
|
### Coding
|
|
|
|
Lead with what changed or what should change. Include files, commands, and verification. Do not narrate every exploration step.
|
|
|
|
### Research discussion
|
|
|
|
Separate fact, inference, and recommendation. Surface weak assumptions early.
|
|
|
|
### Writing and editing
|
|
|
|
Prefer compressed, reader-facing claims. Avoid inflated wording. Make the contribution, evidence, and limitation visible.
|
|
|
|
### Knowledge work
|
|
|
|
State the knowledge problem first: decision, evidence trail, synthesis, reusable method, or practice artifact.
|
|
|
|
### Long-running work
|
|
|
|
Report roadmarks:
|
|
|
|
- step / total
|
|
- processed amount
|
|
- output path
|
|
- next checkpoint
|
|
- visible blocker
|
|
|
|
### File operations
|
|
|
|
Always report:
|
|
|
|
- input path
|
|
- output path
|
|
- changed files
|
|
- untouched files
|
|
- verification performed
|
|
|
|
## 10. Common Mistakes To Avoid
|
|
|
|
- Teaching the whole background when the user needs a decision.
|
|
- Asking a question before reading discoverable files.
|
|
- Using abstract verbs without a concrete action.
|
|
- Reporting "done" without verification.
|
|
- Hiding uncertainty until the end.
|
|
- Giving too many options without a recommendation.
|
|
- Treating user criticism as conflict instead of useful signal.
|