design-patterns
Skill2 starsChanged 3 months agoApache-2.0View on GitHub
Rust design patterns for PTK. Newtype, Builder, RAII, Trait Objects, State Machine. Applied to CLI filter modules. Use when designing new modules or refactoring existing ones.
37 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- bryanus1/agent-skillstheir own version, first seen Nov 16, 2026
- travissmithv1/claude-skillstheir own version, first seen Nov 16, 2026
- Ajustor/claude-skillstheir own version, first seen Nov 16, 2026
- AiryLab/agentvaulttheir own version, first seen Nov 15, 2026
- thistleknot/skillstheir own version, first seen Nov 8, 2026
- gustaferiksson/skillstheir own version, first seen Nov 7, 2026
Used with
Projects with it also use logging-patterns, solid-principles and 5 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
DIL8654Skilllogging-patterns
Keep logs structured, correlated, low-noise, and safe for production support. Use when adding operational logging, reviewing observability, or improving diagnostics in .NET services.
Also in 7 projects that use this
nek1987Skillsolid-principles
SOLID object-oriented design principles for maintainable code
Also in 5 projects that use this
mstuder-slalomSkilljpa-patterns
JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot.
Also in 6 projects that use this
DIL8654Skillapi-contract-review
Review ASP.NET Core Web API contracts for HTTP semantics, versioning, backward compatibility, and response consistency. Use when the user asks to review an API, check endpoints, validate REST behavior, or before releasing contract changes.
Also in 3 projects that use this
zavierSkilljava-code-review
Java代码审查技能,通过比较两个git分支进行自动化代码审查
Also in 3 projects that use this
LangChainSkilltesting-patterns
Unit testing and integration testing best practices
Also in 3 projects that use this
Other versions37 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- rtk-ai/rtk★ 87k92% same
Wrote their own version · 36
- piomin/claude-ai-spring-boot★ 1.4ksame name
- decebals/claude-code-java★ 763same name
- waybarrios/opencode-power-pack★ 547same name
- FlorianBruniaux/ccboard★ 94same name
- nimadorostkar/Claude-Skills-collection★ 37same name
- DIL8654/claude-code-dotnet-template★ 8same name
- tstapler/dotfiles★ 8same name
- cookieMonsterDev/agents-skills★ 7same name
- piomin/claude-ai-quarkus★ 7same name
- ralvarez-ai/ralvaskills★ 4same name
26 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- code-simplifierSkill
- issue-triageSkill
- performanceSkill
- pr-reviewSkill
- pr-triageSkill
- ptk-tddSkill
- ptk-triageSkill
- repo-recapSkill
- security-guardianSkill
- shipSkill
- tdd-rustSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 7 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 36 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Use when: wrapping primitive types to prevent misuse (command names, paths, token counts).
- Distinctive: line 53
Use when: a struct has 4+ optional fields, many with defaults.
- Distinctive: line 78
When NOT to use Builder: if the struct has 1-3 fields with obvious meaning.
- Distinctive: line 82
Use when: parsing multi-section output (test results, build output) where context changes behavior.
- Distinctive: line 120
Use when: different command families need the same interface.
- Distinctive: line 145
Use when: managing resources that need cleanup (temp files, SQLite connections).
- Distinctive: line 170
Use when: a command has multiple filtering modes (e.g., compact vs.
- Very specific: line 190
Use when: you need to add methods to types you don't own (like &str for PTK-specific parsing).
“Common” is measured: kept by at least 6 in 10 of the 36 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PTK Rust Design Patterns
Patterns that apply to PTK's filter module architecture. Focused on CLI tool patterns, not web/service patterns.
Pattern 1: Newtype (Type Safety)
Use when: wrapping primitive types to prevent misuse (command names, paths, token counts).
// Without Newtype — easy to mix up
fn track(input_tokens: usize, output_tokens: usize) { ... }
track(output_tokens, input_tokens); // Silent bug!
// With Newtype — compile error on swap
pub struct InputTokens(pub usize);
pub struct OutputTokens(pub usize);
fn track(input: InputTokens, output: OutputTokens) { ... }
track(OutputTokens(100), InputTokens(400)); // Compile error ✅// Practical PTK example: command name validation
pub struct CommandName(String);
impl CommandName {
pub fn new(s: &str) -> Result<Self> {
if s.contains(';') || s.contains('|') || s.contains('`') {
anyhow::bail!("Invalid command name: shell metacharacters");
}
Ok(Self(s.to_string()))
}
pub fn as_str(&self) -> &str { &self.0 }
}Pattern 2: Builder (Complex Configuration)
Use when: a struct has 4+ optional fields, many with defaults.
#[derive(Default)]
pub struct FilterConfig {
max_lines: Option<usize>,
strip_ansi: bool,
show_warnings: bool,
truncate_at: Option<usize>,
}
impl FilterConfig {
pub fn new() -> Self { Self::default() }
pub fn max_lines(mut self, n: usize) -> Self { self.max_lines = Some(n); self }
pub fn strip_ansi(mut self, v: bool) -> Self { self.strip_ansi = v; self }
pub fn show_warnings(mut self, v: bool) -> Self { self.show_warnings = v; self }
}
// Usage — readable, no positional arg confusion
let config = FilterConfig::new()
.max_lines(50)
.strip_ansi(true)
.show_warnings(false);When NOT to use Builder: if the struct has 1-3 fields with obvious meaning. Over-engineering for simple cases.
Pattern 3: State Machine (Parser/Filter Flows)
Use when: parsing multi-section output (test results, build output) where context changes behavior.
// PTK example: pytest output parsing
#[derive(Debug, PartialEq)]
enum ParseState {
LookingForTests,
InTestOutput,
InFailureSummary,
Done,
}
fn parse_pytest(input: &str) -> String {
let mut state = ParseState::LookingForTests;
let mut failures = Vec::new();
for line in input.lines() {
match state {
ParseState::LookingForTests => {
if line.contains("FAILED") || line.contains("ERROR") {
state = ParseState::InFailureSummary;
failures.push(line);
}
}
ParseState::InFailureSummary => {
if line.starts_with("=====") { state = ParseState::Done; }
else { failures.push(line); }
}
ParseState::Done => break,
_ => {}
}
}
failures.join("\n")
}Pattern 4: Trait Object (Command Dispatch)
Use when: different command families need the same interface. Avoids massive match arms.
// Define a common interface for filters
pub trait OutputFilter {
fn filter(&self, input: &str) -> Result<String>;
fn command_name(&self) -> &str;
}
pub struct GitFilter;
pub struct CargoFilter;
impl OutputFilter for GitFilter {
fn filter(&self, input: &str) -> Result<String> { filter_git(input) }
fn command_name(&self) -> &str { "git" }
}
// PTK currently uses match-based dispatch in main.rs (simpler, no dynamic dispatch overhead)
// Trait objects are useful if filter registry becomes dynamic (e.g., TOML-loaded plugins)Note: PTK's current match dispatch in main.rs is intentional — static dispatch, zero overhead. Only move to trait objects if the match arm count exceeds ~20 commands.
Pattern 5: RAII (Resource Management)
Use when: managing resources that need cleanup (temp files, SQLite connections).
// PTK tee.rs — RAII for temp output files
pub struct TeeFile {
path: PathBuf,
}
impl TeeFile {
pub fn create(content: &str) -> Result<Self> {
let path = tee_path()?;
fs::write(&path, content)
.with_context(|| format!("Failed to write tee file: {}", path.display()))?;
Ok(Self { path })
}
pub fn path(&self) -> &Path { &self.path }
}
// No explicit cleanup needed — file persists intentionally (rotation handled separately)
// If cleanup were needed: impl Drop { fn drop(&mut self) { let _ = fs::remove_file(&self.path); } }Pattern 6: Strategy (Swappable Filter Logic)
Use when: a command has multiple filtering modes (e.g., compact vs. verbose).
pub enum FilterMode {
Compact, // Show only failures/errors
Summary, // Show counts + top errors
Full, // Pass through unchanged
}
pub fn apply_filter(input: &str, mode: FilterMode) -> String {
match mode {
FilterMode::Compact => filter_compact(input),
FilterMode::Summary => filter_summary(input),
FilterMode::Full => input.to_string(),
}
}Pattern 7: Extension Trait (Add Methods to External Types)
Use when: you need to add methods to types you don't own (like &str for PTK-specific parsing).
pub trait PtkStrExt {
fn is_error_line(&self) -> bool;
fn is_warning_line(&self) -> bool;
fn token_count(&self) -> usize;
}
impl PtkStrExt for str {
fn is_error_line(&self) -> bool {
self.starts_with("error") || self.contains("[E")
}
fn is_warning_line(&self) -> bool {
self.starts_with("warning")
}
fn token_count(&self) -> usize {
self.split_whitespace().count()
}
}
// Usage
if line.is_error_line() { ... }
let tokens = output.token_count();PTK Pattern Selection Guide
| Situation | Pattern | Avoid |
New *_cmd.rs filter module | Standard module pattern (see CLAUDE.md) | Over-abstracting |
| 4+ optional config fields | Builder | Struct literal |
| Multi-phase output parsing | State Machine | Nested if/else |
| Type-safe wrapper around string | Newtype | Raw String |
Adding methods to &str | Extension Trait | Free functions |
| Resource with cleanup | RAII / Drop | Manual cleanup |
| Dynamic filter registry | Trait Object | Match sprawl |
Anti-Patterns in PTK Context
// ❌ Generic over-engineering for one command
pub trait Filterable<T: CommandArgs + Send + Sync + 'static> { ... }
// ✅ Just write the function
pub fn filter_git_log(input: &str) -> Result<String> { ... }
// ❌ Singleton registry with global state
static FILTER_REGISTRY: Mutex<HashMap<String, Box<dyn Filter>>> = ...;
// ✅ Match in main.rs — simple, zero overhead, easy to trace
// ❌ Async traits for "future-proofing"
#[async_trait]
pub trait Filter { async fn apply(&self, input: &str) -> Result<String>; }
// ✅ Synchronous — PTK is single-threaded by design
pub trait Filter { fn apply(&self, input: &str) -> Result<String>; }Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

