diff --git a/PATTERN_MIGRATION_GUIDE.md b/PATTERN_MIGRATION_GUIDE.md index f4ce9e9..687fb1e 100644 --- a/PATTERN_MIGRATION_GUIDE.md +++ b/PATTERN_MIGRATION_GUIDE.md @@ -66,9 +66,9 @@ This change aligns with established pattern naming conventions: | Rushing Into AI | Premature Adoption | Added negative prefix | "Premature" clearly indicates timing failure | | Context Drift | Broken Context | Added negative prefix | "Broken" indicates failure state | | Unrestricted Access | Unrestricted Access | No change | Already compliant | -| Shared Agent Workspaces | Overlapping Workspaces | Changed to negative implication | "Overlapping" suggests conflict | +| Shared Agent Workspaces | Conflicting Workspaces | Changed to negative implication | "Conflicting" clearly indicates problem | | Ad-Hoc AI Development | Unplanned Development | Added negative prefix | "Unplanned" clearly negative | -| Prompt-Only AI Development | Isolated Prompting | Simplified, negative implication | "Isolated" suggests insufficient approach | +| Prompt-Only AI Development | Disconnected Prompting | Simplified, negative implication | "Disconnected" clearly indicates isolation from tools | | Vague Issue Generation | Under-Specified Issues | Added negative prefix | "Under-Specified" indicates insufficiency | | Missing CI Integration | Broken Integration | Added negative prefix | "Broken" indicates failure | | Implementation-First AI | Spec-Ignored | Symmetrical with "Spec-First" | Opposite of the pattern | @@ -80,7 +80,7 @@ This change aligns with established pattern naming conventions: | Knowledge Hoarding | Over-Documentation | Changed to "Over-" prefix | More technical description | | Context Bloat | Bloated Context | Adjusted word order | "Bloated" is negative adjective | | Unconstrained Generation | Unconstrained Generation | No change | Already compliant | -| Constraint Overload | Constraint Overload | No change | Already compliant | +| Constraint Overload | Over-Constrained | Changed to negative prefix | "Over-" prefix indicates excess | | Pseudo-Atomic Tasks | False Atomicity | Changed to "False" | More precise negative indicator | | Over-Decomposition | Over-Decomposition | No change | Already compliant | | Black Box Development | Blind Development | Changed "Black Box" to "Blind" | Simpler, maintains meaning | diff --git a/README.md b/README.md index a6ee23c..5851207 100644 --- a/README.md +++ b/README.md @@ -458,7 +458,7 @@ Modern AI development platforms provide enterprise-grade implementations of thes **Anti-pattern: Unrestricted Access** Allowing AI tools full system access risks credential leaks, data breaches, and security compliance violations. -**Anti-pattern: Overlapping Workspaces** +**Anti-pattern: Conflicting Workspaces** Allowing multiple parallel agents to write to the same directories creates race conditions, file conflicts, and unpredictable behavior that can corrupt the development environment. --- @@ -622,7 +622,7 @@ See [examples/tool-integration/](examples/tool-integration/) for: - Usage patterns and deployment guidelines - Integration with [Security Sandbox](#security-sandbox) -**Anti-pattern: Isolated Prompting** +**Anti-pattern: Disconnected Prompting** Attempting to solve complex data analysis, system integration, or real-time problems using only natural language prompts without providing AI access to actual data sources, APIs, or system tools. This leads to hallucinated responses, outdated information, and inability to interact with real systems. --- @@ -1372,7 +1372,7 @@ Good: "Reduce p99 latency to <50ms without new dependencies" **Anti-pattern: Unconstrained Generation** Giving AI vague instructions like "make it better" or "add features" leads to over-engineered solutions that are hard to maintain and review. -**Anti-pattern: Constraint Overload** +**Anti-pattern: Over-Constrained** Adding too many constraints ("use exactly 50 lines, 2 methods, no dependencies, 100% test coverage, sub-10ms response time") paralyzes AI decision-making and produces suboptimal solutions. --- diff --git a/experiments/README.md b/experiments/README.md index 7f2815d..d3fcb6d 100644 --- a/experiments/README.md +++ b/experiments/README.md @@ -1143,7 +1143,7 @@ cat .ai/context-usage.log | grep -oE "rules/[^/]+/[^ ]+" | sort | uniq -c | sort - Split by clear domains: security/, development/, operations/ - Aim for 5-10 specialized files, not 50 -#### Anti-pattern: No Loading Guidance +#### Anti-pattern: Missing Guidance **Problem**: Creating specialized rule files but not telling the AI when to load them. @@ -1451,7 +1451,7 @@ Simon's approach: - Mark repo as `noindex` for search engines - *"I still like to keep AI-generated content out of search, to avoid contributing more to the dead internet."* -#### Anti-pattern: Secret Leakage +#### Anti-pattern: Leaked Secrets **Problem**: Running unrestricted agents on production repos containing credentials. @@ -1459,7 +1459,7 @@ Simon warns: *"A prompt injection attack of the lethal trifecta variety could ea **Solution**: Only use unrestricted access on dedicated, secret-free research repos. -#### Anti-pattern: Proving Impossibility +#### Anti-pattern: Unfounded Impossibility **Problem**: Expecting agents to prove something can't be done. diff --git a/experiments/examples/asynchronous-research/README.md b/experiments/examples/asynchronous-research/README.md index f412770..096cdb7 100644 --- a/experiments/examples/asynchronous-research/README.md +++ b/experiments/examples/asynchronous-research/README.md @@ -373,13 +373,13 @@ python automation/result-parser.py research-folder/ **Solution**: Keep research in dedicated repo, mark as `noindex`. -### ❌ Secret Leakage +### ❌ Leaked Secrets **Problem**: Running unrestricted agents on repos with production secrets. **Solution**: Only use unrestricted access on dedicated, secret-free research repos. -### ❌ Proving Impossibility +### ❌ Unfounded Impossibility **Problem**: Expecting agents to prove something can't be done. diff --git a/pattern-spec.md b/pattern-spec.md index c04224d..eb23f72 100644 --- a/pattern-spec.md +++ b/pattern-spec.md @@ -224,6 +224,35 @@ Before finalizing an antipattern name, verify: - Provide specific consequences - Examples: "Manual Policy Translation", "Alert Fatigue", "Blind Chaos Testing" +### Pattern Length Guidelines + +**Recommended maximum lengths:** +- **Complete pattern**: 200-400 lines (target), 600 lines (max before splitting) +- **Description**: 1-2 sentences +- **Core implementation**: 150-300 lines +- **Individual anti-patterns**: 50-100 lines each +- **Code examples in README**: 30-50 lines max + +**When a pattern exceeds 600 lines:** +1. Review for unnecessary repetition or verbosity +2. Move detailed implementations to `examples/pattern-name/` directory +3. Consider splitting into multiple focused patterns +4. Remove "nice-to-have" scenarios that don't demonstrate core concepts + +**Philosophy**: Patterns should be **scannable in 2-3 minutes**. Readers should grasp the core concept quickly and reference examples/ for deep implementation details. + +**Enforcement Strategy** + +For AI-generated patterns: +1. **Auto-warning at 500+ lines**: "This pattern is getting long. Review for bloat." +2. **Hard review at 600+ lines**: "Consider splitting or moving detail to examples/" +3. **Guidance**: "Each additional 100 lines should add significant new value" + +**Quality over quantity:** +- ✅ 300 well-focused lines > 600 lines with repetition +- ✅ Clear core examples > exhaustive scenario coverage +- ✅ Scannable structure > comprehensive documentation + ## Formatting Standards ### Code Blocks diff --git a/scripts/apply-pattern-renames.sh b/scripts/apply-pattern-renames.sh index 0fc0513..a10d560 100755 --- a/scripts/apply-pattern-renames.sh +++ b/scripts/apply-pattern-renames.sh @@ -98,9 +98,9 @@ apply_renames() { # Antipattern Renames sed -i 's/\*\*Anti-pattern: Rushing Into AI\*\*/\*\*Anti-pattern: Premature Adoption\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Context Drift\*\*/\*\*Anti-pattern: Broken Context\*\*/g' "$file" - sed -i 's/\*\*Anti-pattern: Shared Agent Workspaces\*\*/\*\*Anti-pattern: Overlapping Workspaces\*\*/g' "$file" + sed -i 's/\*\*Anti-pattern: Shared Agent Workspaces\*\*/\*\*Anti-pattern: Conflicting Workspaces\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Ad-Hoc AI Development\*\*/\*\*Anti-pattern: Unplanned Development\*\*/g' "$file" - sed -i 's/\*\*Anti-pattern: Prompt-Only AI Development\*\*/\*\*Anti-pattern: Isolated Prompting\*\*/g' "$file" + sed -i 's/\*\*Anti-pattern: Prompt-Only AI Development\*\*/\*\*Anti-pattern: Disconnected Prompting\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Vague Issue Generation\*\*/\*\*Anti-pattern: Under-Specified Issues\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Missing CI Integration\*\*/\*\*Anti-pattern: Broken Integration\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Implementation-First AI\*\*/\*\*Anti-pattern: Spec-Ignored\*\*/g' "$file"