refactor(coding-agent): standardized XML tags and RFC 2119 keywords across prompts
- Standardized XML tag naming from snake_case to kebab-case across 50+ prompt files for consistency. - Replaced imperative language with RFC 2119 keywords (MUST/SHOULD/MAY/MUST NOT) throughout system and tool prompts for clarity. - Removed artifactsDir parameter from Python executor and simplified environment variable handling to use PI_SESSION_FILE only. - Renamed read_path.md to read-path.md and updated memory guidance with hierarchy rules and conflict resolution workflow. - Added noEscape option to bash URL expansion and extracted cwd parameter from leading cd commands for improved path handling. - Exported NO_PAGER_ENV constant from bash-interactive module for centralized environment variable management.
This commit is contained in:
@@ -199,7 +199,7 @@ Keep going until complete. This matters.
|
||||
### System Prompt (Main Agent)
|
||||
|
||||
```markdown
|
||||
<system_directive>
|
||||
<system-directive>
|
||||
XML tags in this prompt are system-level instructions. They are not suggestions.
|
||||
|
||||
Tag hierarchy (by enforcement level):
|
||||
@@ -210,7 +210,7 @@ Tag hierarchy (by enforcement level):
|
||||
- `<instruction>` — How to operate. Follow precisely.
|
||||
- `<conditions>` — When rules apply. Check before acting.
|
||||
- `<avoid>` — Anti-patterns. Prefer alternatives.
|
||||
</system_directive>
|
||||
</system-directive>
|
||||
|
||||
You are a [specific role with credentials].
|
||||
|
||||
@@ -284,6 +284,31 @@ Good: "Critical: X."
|
||||
"Keep going until fully resolved."
|
||||
```
|
||||
|
||||
### Normative Language (RFC 2119)
|
||||
|
||||
All prompt prose that prescribes behavior MUST use RFC 2119 key words in **full caps**. This removes ambiguity about whether an instruction is absolute or advisory.
|
||||
|
||||
| Keyword | Meaning | Replaces |
|
||||
| --- | --- | --- |
|
||||
| **MUST** / **REQUIRED** | Absolute requirement | "always", "make sure", "ensure", "do" |
|
||||
| **MUST NOT** / **PROHIBITED** | Absolute prohibition | "never", "do not", "don't", "strictly prohibited" |
|
||||
| **SHOULD** / **RECOMMENDED** | Strong preference; deviation allowed with known tradeoffs | "prefer", "recommend", "it's best to" |
|
||||
| **SHOULD NOT** / **NOT RECOMMENDED** | Strong discouragement; deviation allowed with known tradeoffs | "avoid", "try not to" |
|
||||
| **MAY** / **OPTIONAL** | Truly optional | "can", "may", "you could" |
|
||||
|
||||
```
|
||||
Bad: "Never edit from a grep snippet alone"
|
||||
Good: "You MUST NOT edit from a grep snippet alone"
|
||||
|
||||
Bad: "Prefer unit tests over mocks"
|
||||
Good: "You SHOULD prefer unit tests over mocks"
|
||||
|
||||
Bad: "Make sure to run lsp references before modifying a symbol"
|
||||
Good: "You MUST run lsp references before modifying any symbol"
|
||||
```
|
||||
|
||||
**What not to convert**: factual/descriptive sentences (what a tool returns, what a parameter does), code blocks, examples, schema definitions, Handlebars template syntax. Only prescriptive prose gets RFC treatment.
|
||||
|
||||
### Positive Framing
|
||||
|
||||
Models process "Always do Y" better than "Don't do X":
|
||||
@@ -573,6 +598,7 @@ Read-only. Call `submit_result` when done. This matters.
|
||||
- [ ] **Specificity**: Exact formats, limits, constraints—not vague?
|
||||
- [ ] **Token efficiency**: Each sentence justifies its cost?
|
||||
- [ ] **Verification**: External feedback loop if correctness matters?
|
||||
- [ ] **RFC 2119 normative language**: All prescriptive sentences use MUST/MUST NOT/SHOULD/MAY in caps?
|
||||
- [ ] **Persistence**: "Keep going until complete" for complex tasks?
|
||||
|
||||
**High-impact interventions: persistence, tool verification, planning, context positioning, urgency.**
|
||||
|
||||
Reference in New Issue
Block a user