Initial commit: The Collective Hub planning documentation
This commit is contained in:
@@ -0,0 +1,240 @@
|
||||
<xml_structuring_best_practices>
|
||||
<overview>
|
||||
XML tags help LLMs parse prompts more accurately, leading to higher-quality outputs.
|
||||
This guide covers best practices for structuring mode instructions using XML.
|
||||
</overview>
|
||||
|
||||
<why_use_xml_tags>
|
||||
<benefit type="clarity">
|
||||
Clearly separate different parts of your instructions and ensure well-structured content
|
||||
</benefit>
|
||||
<benefit type="accuracy">
|
||||
Reduce errors caused by the model misinterpreting parts of your instructions
|
||||
</benefit>
|
||||
<benefit type="flexibility">
|
||||
Easily find, add, remove, or modify parts of instructions without rewriting everything
|
||||
</benefit>
|
||||
<benefit type="parseability">
|
||||
Having the model use XML tags in its output makes it easier to extract specific parts of responses
|
||||
</benefit>
|
||||
</why_use_xml_tags>
|
||||
|
||||
<core_principles>
|
||||
<principle name="consistency">
|
||||
<description>Use the same tag names throughout your instructions</description>
|
||||
<example>
|
||||
Always use <step> for workflow steps, not sometimes <action> or <task>
|
||||
</example>
|
||||
</principle>
|
||||
|
||||
<principle name="semantic_naming">
|
||||
<description>Tag names should clearly describe their content</description>
|
||||
<good_examples>
|
||||
<tag>detailed_steps</tag>
|
||||
<tag>error_handling</tag>
|
||||
<tag>validation_rules</tag>
|
||||
</good_examples>
|
||||
<bad_examples>
|
||||
<tag>stuff</tag>
|
||||
<tag>misc</tag>
|
||||
<tag>data1</tag>
|
||||
</bad_examples>
|
||||
</principle>
|
||||
|
||||
<principle name="hierarchical_nesting">
|
||||
<description>Nest tags to show relationships and structure</description>
|
||||
<example>
|
||||
<workflow>
|
||||
<phase name="preparation">
|
||||
<step>Gather requirements</step>
|
||||
<step>Validate inputs</step>
|
||||
</phase>
|
||||
<phase name="execution">
|
||||
<step>Process data</step>
|
||||
<step>Generate output</step>
|
||||
</phase>
|
||||
</workflow>
|
||||
</example>
|
||||
</principle>
|
||||
</core_principles>
|
||||
|
||||
<common_tag_patterns>
|
||||
<pattern name="workflow_structure">
|
||||
<usage>For step-by-step processes</usage>
|
||||
<template>
|
||||
<workflow>
|
||||
<overview>High-level description</overview>
|
||||
<prerequisites>
|
||||
<prerequisite>Required condition 1</prerequisite>
|
||||
<prerequisite>Required condition 2</prerequisite>
|
||||
</prerequisites>
|
||||
<steps>
|
||||
<step number="1">
|
||||
<title>Step Title</title>
|
||||
<description>What this step accomplishes</description>
|
||||
<actions>
|
||||
<action>Specific action to take</action>
|
||||
</actions>
|
||||
<validation>How to verify success</validation>
|
||||
</step>
|
||||
</steps>
|
||||
</workflow>
|
||||
</template>
|
||||
</pattern>
|
||||
|
||||
<pattern name="examples_structure">
|
||||
<usage>For providing code examples and demonstrations</usage>
|
||||
<template>
|
||||
<examples>
|
||||
<example name="descriptive_name">
|
||||
<description>What this example demonstrates</description>
|
||||
<context>When to use this approach</context>
|
||||
<code language="typescript">
|
||||
// Your code example here
|
||||
</code>
|
||||
<explanation>
|
||||
Key points about the implementation
|
||||
</explanation>
|
||||
</example>
|
||||
</examples>
|
||||
</template>
|
||||
</pattern>
|
||||
|
||||
<pattern name="guidelines_structure">
|
||||
<usage>For rules and best practices</usage>
|
||||
<template>
|
||||
<guidelines category="category_name">
|
||||
<guideline priority="high">
|
||||
<rule>The specific rule or guideline</rule>
|
||||
<rationale>Why this is important</rationale>
|
||||
<exceptions>When this doesn't apply</exceptions>
|
||||
</guideline>
|
||||
</guidelines>
|
||||
</template>
|
||||
</pattern>
|
||||
|
||||
<pattern name="decision_guidance_structure">
|
||||
<usage>For documenting decision criteria and guardrails</usage>
|
||||
<template>
|
||||
<decision_guidance>
|
||||
<principles>
|
||||
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||
</principles>
|
||||
|
||||
<constraints>
|
||||
Constraints and guardrails (e.g., permissions, file restrictions, or other limits).
|
||||
</constraints>
|
||||
|
||||
<validation>
|
||||
What to verify after changes (cohesion, examples updated, boundaries clear).
|
||||
</validation>
|
||||
</decision_guidance>
|
||||
</template>
|
||||
</pattern>
|
||||
</common_tag_patterns>
|
||||
|
||||
<formatting_guidelines>
|
||||
<guideline name="indentation">
|
||||
Use consistent indentation (2 or 4 spaces) for nested elements
|
||||
</guideline>
|
||||
<guideline name="line_breaks">
|
||||
Add line breaks between major sections for readability
|
||||
</guideline>
|
||||
<guideline name="comments">
|
||||
Use XML comments <!-- like this --> to explain complex sections
|
||||
</guideline>
|
||||
<guideline name="cdata_sections">
|
||||
Use CDATA for code blocks or content with special characters:
|
||||
<code>your code here</code>
|
||||
</guideline>
|
||||
<guideline name="attributes_vs_elements">
|
||||
Use attributes for metadata, elements for content:
|
||||
<example type="good">
|
||||
<step number="1" priority="high">
|
||||
<description>The actual step content</description>
|
||||
</step>
|
||||
</example>
|
||||
</guideline>
|
||||
<guideline name="verbosity">
|
||||
Keep narrative outputs concise; reserve detailed exposition for code, diffs, and structured outputs. Prefer readable, maintainable code with clear names; avoid one-liners unless explicitly requested.
|
||||
</guideline>
|
||||
</formatting_guidelines>
|
||||
|
||||
<anti_patterns>
|
||||
<anti_pattern name="flat_structure">
|
||||
<description>Avoid completely flat structures without hierarchy</description>
|
||||
<bad>
|
||||
<instructions>
|
||||
|
||||
<item1>Do this</item1>
|
||||
|
||||
<item2>Then this</item2>
|
||||
|
||||
<item3>Finally this</item3>
|
||||
|
||||
</instructions>
|
||||
</bad>
|
||||
<good>
|
||||
<instructions>
|
||||
<steps>
|
||||
<step order="1">Do this</step>
|
||||
<step order="2">Then this</step>
|
||||
<step order="3">Finally this</step>
|
||||
</steps>
|
||||
</instructions>
|
||||
</good>
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="inconsistent_naming">
|
||||
<description>Don't mix naming conventions</description>
|
||||
<bad>
|
||||
Mixing camelCase, snake_case, and kebab-case in tag names
|
||||
</bad>
|
||||
<good>
|
||||
Pick one convention (preferably snake_case for XML) and stick to it
|
||||
</good>
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="overly_generic_tags">
|
||||
<description>Avoid tags that don't convey meaning</description>
|
||||
<bad>data, info, stuff, thing, item</bad>
|
||||
<good>user_input, validation_result, error_message, configuration</good>
|
||||
</anti_pattern>
|
||||
<anti_pattern name="over_clarifying_questions">
|
||||
<description>Avoid asking the user to confirm obvious next steps on straightforward tasks</description>
|
||||
<bad>Asking multiple clarifying questions before acting when the task is simple</bad>
|
||||
<good>Proceed when next steps are clear; ask only when critical ambiguity remains; document assumptions</good>
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="excessive_searching">
|
||||
<description>Avoid repetitive or redundant searches when the relevant target is already identified</description>
|
||||
<bad>Running multiple identical searches instead of acting</bad>
|
||||
<good>Stop once the change is clearly identified; then implement</good>
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="over_specifying_runtime_behavior">
|
||||
<description>Avoid duplicating runtime behavior that is already defined elsewhere</description>
|
||||
<bad>Documenting execution constraints, operation ordering, or invocation details</bad>
|
||||
<good>Focus on intent, artifacts, decision criteria, and validation expectations</good>
|
||||
</anti_pattern>
|
||||
</anti_patterns>
|
||||
|
||||
<integration_tips>
|
||||
<tip>
|
||||
Reference XML content in instructions:
|
||||
"Using the workflow defined in <workflow> tags..."
|
||||
</tip>
|
||||
<tip>
|
||||
Combine XML structure with other techniques like multishot prompting
|
||||
</tip>
|
||||
<tip>
|
||||
Use XML tags in expected outputs to make parsing easier
|
||||
</tip>
|
||||
<tip>
|
||||
Create reusable XML templates for common patterns
|
||||
</tip>
|
||||
</integration_tips>
|
||||
</xml_structuring_best_practices>
|
||||
Reference in New Issue
Block a user