diff --git a/README.md b/README.md index 4e2a094..97b162f 100644 --- a/README.md +++ b/README.md @@ -18,17 +18,36 @@ These are derived from what mature Go codebases *actually do*, not opinions or b ## How to use -### Writing code +Give your agent these instructions depending on the task: -> Read the relevant pattern files from this repo before writing code. Your implementation must follow the documented patterns — if you deviate, justify why in a comment. Check `smells/` to make sure you're not introducing a known anti-pattern. +### Solving a problem + +> You have access to a patterns repo containing proven solutions to recurring Go problems. When I describe a problem: +> +> 1. Identify which pattern files are relevant (read them) +> 2. Check if my problem matches a "When to use" case +> 3. Check if it matches a "When NOT to use" case +> 4. If a pattern fits: suggest the approach, cite the pattern, explain why it applies here +> 5. If no pattern fits: say so, and suggest an approach grounded in the principles you see across the patterns +> 6. If my problem matches a smell: warn me before I make the mistake +> +> Never suggest something that contradicts a documented pattern without explicitly calling out the deviation and justifying it. ### Reviewing code -> Read the relevant pattern files from this repo. For each function or module in the diff, verify it follows the documented pattern. If the code deviates, flag it with a reference to the specific pattern and section. A deviation without justification is a finding. +> You have access to a patterns repo that defines how Go code should be written. For each file in the diff: +> +> 1. Read the relevant pattern files +> 2. Verify the code follows the documented patterns +> 3. If it deviates: flag it with a reference to the specific pattern, section, and why it matters +> 4. If it matches a smell: flag it as a known anti-pattern +> 5. A deviation without justification is a finding +> +> Don't invent rules. Only flag what the patterns document. ### Evaluating a pattern -> Read the pattern file. Compare against how the following projects handle the same problem: [list projects]. Does the pattern hold? Are there cases where it breaks down? Update the pattern with what you find. +> Read the pattern file. Compare against how the following projects handle the same problem: [list projects]. Does the pattern hold? Are there cases where it breaks down? Should it be updated, split, or retired? File your findings as an issue. ## Patterns vs Conventions