Skip to content
Back to search

claude-config

SkillWorks with Claude CodeGitHub

My claude code customizations / config.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/solatis--claude-config/badge.svg)](/listings/solatis--claude-config)

HTML

<a href="/listings/solatis--claude-config"><img src="/api/listings/solatis--claude-config/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone into your Claude Code configuration directory:

# Per-project
git clone https://github.com/solatis/claude-config .claude

# Global (new setup)
git clone https://github.com/solatis/claude-config ~/.claude

# Global (existing ~/.claude)
cd ~/.claude
git remote add workflow https://github.com/solatis/claude-config
git fetch workflow
git merge workflow/main --allow-unrelated-histories

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 386 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # My Claude Code Workflow
  2. I use Claude Code for most of my work. After months of iteration, I noticed a
  3. pattern: LLM-assisted code rots faster than hand-written code. Technical debt
  4. accumulates because the LLM does not know what it does not know, and neither do
  5. you until it is too late.
  6. This repo is my solution: skills and workflows that force planning before
  7. execution, keep context focused, and catch mistakes before they compound.
  8. ## Why This Exists
  9. LLM-assisted coding fails long-term. Technical debt accumulates because the LLM
  10. cannot see it, and you are moving too fast to notice. I treat this as an
  11. engineering problem, not a tooling problem.
  12. LLMs are tools, not collaborators. When an engineer says "add retry logic",
  13. another engineer infers exponential backoff, jitter, and idempotency. An LLM
  14. infers nothing you do not explicitly state. It cannot read the room. It has no
  15. institutional memory. It will cheerfully implement the wrong thing with perfect
  16. confidence and call it "production-ready".
  17. Larger context windows do not help. Giving an LLM more text is like giving a
  18. human a larger stack of papers; attention drifts to the beginning and end, and
  19. details in the middle get missed. More context makes this worse. Give the LLM
  20. exactly what it needs for the task at hand -- nothing more.
  21. ## Principles
  22. This workflow is built on four principles.
  23. ### Context Hygiene
  24. Each task gets precisely the information it needs -- no more. Sub-agents start
  25. with a fresh context, so architectural knowledge must be encoded somewhere
  26. persistent.
  27. I use a two-file pattern in every directory:
  28. **CLAUDE.md** -- Claude loads these automatically when entering a directory.
  29. Because they load whether needed or not, content must be minimal: a tabular
  30. index with short descriptions and triggers for when to open each file. When
  31. Claude opens `app/web/controller.py`, it retrieves just the indexes along that
  32. path -- not prose it might never need.
  33. **README.md** -- Invisible knowledge: architecture decisions, invariants not
  34. apparent from code. The test: if a developer could learn it by reading source
  35. files, it does not belong here. Claude reads these only when the CLAUDE.md
  36. trigger says to.
  37. The principle is just-in-time context. Indexes load automatically but stay
  38. small. Detailed knowledge loads only when relevant.
  39. The technical writer agent enforces token budgets: ~200 tokens for CLAUDE.md,
  40. ~500 for README.md, 100 for function docs, 150 for module docs. These limits
  41. force discipline -- if you are exceeding them, you are probably documenting what
  42. code already shows. Function docs include "use when..." triggers so the LLM
  43. knows when to reach for them.
  44. The planner workflow maintains this hierarchy automatically. If you bypass the
  45. planner, you maintain it yourself.
  46. ### Planning Before Execution
  47. LLMs make first-shot mistakes. Always. The workflow separates planning from
  48. execution, forcing ambiguities to surface when they are cheap to fix.
  49. Plans capture why decisions were made, what alternatives were rejected, and what
  50. risks were accepted. Plans are written to files. When you clear context and
  51. start fresh, the reasoning survives.
  52. ### Review Cycles
  53. Execution is split into milestones -- smaller units that are manageable and can
  54. be validated individually. This ensures continuous, verified progress. Without
  55. it, execution becomes a waterfall: one small oversight early on and agents
  56. compound each mistake until the result is unusable.
  57. Quality gates run at every stage. A technical writer agent checks clarity; a
  58. quality reviewer checks completeness. The loop runs until both pass.
  59. Plans pass review before execution begins. During execution, each milestone
  60. passes review before the next starts.
  61. ### Cost-Effective Delegation
  62. The orchestrator delegates to smaller agents -- Haiku for straightforward tasks,
  63. Sonnet for moderate complexity. Prompts are injected just-in-time, giving
  64. smaller models precisely the guidance they need at each step.
  65. When quality review fails or problems recur, the orchestrator escalates to
  66. higher-quality models. Expensive models are reserved for genuine ambiguity, not
  67. routine work.
  68. ## Does This Actually Work?
  69. I have not run formal benchmarks. I can only tell you what I have observed using
  70. this workflow to build and maintain non-trivial applications entirely with
  71. Claude Code -- backend systems, data pipelines, streaming applications in C++,
  72. Python, and Go.
  73. The problems I used to hit constantly are gone:
  74. **Ambiguity resolution.** You ask an LLM "make me a sandwich" and it comes back
  75. with a grilled cheese. Technically correct. Not what you meant. The planning
  76. phase forces these misunderstandings to surface before you have built the wrong
  77. thing.
  78. **Code hygiene.** Without review cycles, the same utility function gets
  79. reimplemented fifteen times across a codebase. The quality reviewer catches
  80. this. The technical writer ensures documentation stays consistent.
  81. **LLM-navigable documentation.** Function docs include "use when..." triggers.
  82. CLAUDE.md files tell the LLM which files matter for a given task. The LLM stops
  83. guessing which code is relevant.
  84. Is it better than writing code by hand? I think so, but I cannot speak for
  85. everyone. This workflow is opinionated. I am a backend engineer -- the patterns
  86. should apply to frontend work, but I have not tested that. If you are less
  87. experienced with software engineering, I would like to know whether this helps
  88. or adds overhead.
  89. If you are serious about LLM-assisted coding and want to try a structured
  90. approach, give it a shot. I would like to hear what works and what does not.
  91. ## Quick Start
  92. Clone into your Claude Code configuration directory:
  93. ```bash
  94. # Per-project
  95. git clone https://github.com/solatis/claude-config .claude
  96. # Global (new setup)
  97. git clone https://github.com/solatis/claude-config ~/.claude
  98. # Global (existing ~/.claude)
  99. cd ~/.claude
  100. git remote add workflow https://github.com/solatis/claude-config
  101. git fetch workflow
  102. git merge workflow/main --allow-unrelated-histories
  103. ```
  104. ## Usage
  105. The workflow for non-trivial changes: explore -> plan -> execute.
  106. **1. Explore the problem.** Understand what you are dealing with. Figure out the
  107. solution.
  108. This is relatively free-form. If the project and/or surface area is particularly
  109. large, use the `codebase-analysis` skill to explore the project's code properly
  110. before proposing a solution.
  111. **2. (Optional) Think it through.** I reach for `deepthink` very often, more than
  112. any other skill. It handles analytical questions where you do not know the answer
  113. structure yet -- taxonomy design, trade-offs, definitional questions, evaluative
  114. judgments, exploratory investigations.
  115. It auto-detects complexity. Quick mode reasons directly. Full mode launches
  116. parallel sub-agents with different analytical perspectives, then synthesizes
  117. through agreement patterns. Both self-verify.
  118. So, for most analytical questions, deepthink is enough. It explores your
  119. codebase when context is missing. Reach for specialized skills only when the
  120. question is clearly scoped:
  121. - `problem-analysis`: Root cause analysis specifically
  122. - `decision-critic`: Stress-testing a specific decision
  123. **3. Write a plan.** "Use your planner skill to write a plan to
  124. plans/my-feature.md"
  125. The planner runs your plan through review cycles -- technical writer for
  126. clarity, quality reviewer for completeness -- until it passes.
  127. The planner captures all decisions, tradeoffs, and information not visible from
  128. the code so that this context does not get lost.
  129. **4. Clear context.** `/clear` -- start fresh. You have written everything
  130. needed into the plan.
  131. **5. Execute.** "Use your planner skill to execute plans/my-feature.md"
  132. The planner delegates to sub-agents. It never writes code directly. Each
  133. milestone goes through the developer, then the technical-writer and
  134. quality-reviewer. No milestone starts until the previous one passes review.
  135. Where possible, it executes multiple tasks in parallel.
  136. For detailed breakdowns of each skill, see their READMEs:
  137. - [DeepThink](skills/deepthink/README.md)
  138. - [Codebase Analysis](skills/codebase-analysis/README.md)
  139. - [Problem Analysis](skills/problem-analysis/README.md)
  140. - [Decision Critic](skills/decision-critic/README.md)
  141. - [Planner](skills/planner/README.md)
  142. ### In Practice
  143. I needed to migrate a legacy C# Windows Service from print-based logging to
  144. something that actually rotates files.
  145. The codebase had a homegrown Log() method writing to a single file with
  146. File.AppendAllText. No rotation, no log levels, synchronous I/O blocking the
  147. thread. Six Console.WriteLine calls scattered elsewhere went nowhere when
  148. running as a service.
  149. I started with exploration and analysis in a single prompt:
  150. ```
  151. Use your codebase analysis skill to briefly explore this C# project,
  152. with a focus on all the places where debug logs are currently emitted.
  153. Then use your problem analysis skill to think through an appropriate
  154. logging framework:
  155. * must work with .NET Framework 4.8.1
  156. * must support log rotation out of the box
  157. * we run multiple processes on the same machine, so it needs structured
  158. multi-process support
  159. ```
  160. The codebase analysis found 31 call sites and the Console.WriteLine leakage. The
  161. problem analysis evaluated NLog, Serilog, log4net, and
  162. Microsoft.Extensions.Logging against my constraints.
  163. The recommendation was NLog. It handles rotation and async out of the box.
  164. Multi-process support comes from layout variables. Serilog would work but
  165. requires three packages for the same functionality.
  166. I agreed with the recommendation. Not a complicated decision, so I skipped the
  167. `decision-critic` and moved to planning:
  168. ```
  169. Use your planner skill to write an implementation plan to: plan-logging.md
  170. ```
  171. The planner surfaced two ambiguities:
  172. 1. Replace all Log() call sites, or just the implementation? Obvious to a human,
  173. but worth clarifying upfront.
  174. 2. Log rotation defaults. The planner assumed 1-day rotation, but I also need
  175. size-based rotation at 1GB.
  176. The plan went through review. The technical writer flagged comments that
  177. explained what rather than why -- the NLog.config had comments like "configures
  178. file target" instead of explaining the rotation strategy. The quality reviewer
  179. caught two issues I would have missed: no explicit LogManager.Shutdown() in the
  180. service's OnStop() handler, and incorrect file paths missing the src/ prefix.
  181. These are the bugs that ship to production when you skip review cycles. The
  182. shutdown issue would have caused log loss on service restart. The path issue
  183. would have failed silently.
  184. After fixes, I cleared context and executed:
  185. ```
  186. Use your planner skill to execute: @plan-logging.md
  187. ```
  188. The developer, debugger, technical writer, and quality reviewer run the
  189. implementation. Each milestone passes review before the next starts. If the
  190. implementation deviated from the plan, I would know.
  191. ## Other Skills
  192. Not every task needs the full planning workflow. These skills handle specific
  193. concerns.
  194. ### DeepThink
  195. I use this skill multiple times a day -- whenever I do not know what shape the
  196. answer should take.
  197. Unlike `problem-analysis` or `decision-critic`, deepthink has no fixed
  198. structure. It handles trade-offs, taxonomy questions, evaluative judgments --
  199. whatever you throw at it.
  200. So, when do I reach for it?
  201. Meta-cognitive debugging. I keep making the same mistake. The LLM keeps
  202. misunderstanding the task. Why? Something is broken and I need to see it before
  203. I can fix it.
  204. Strategy evaluation. Multiple valid approaches exist (and gut feel is not
  205. enough). PDF conversion: download the TeX source, parse the PDF directly, or
  206. let the LLM render it visually. S3 artifact versioning: timestamp paths,
  207. pointer files, checksums. Systematic comparison beats intuition.
  208. Best practices research. What is the canonical approach? How do mature CI/CD
  209. systems handle artifact versioning? Industry patterns likely exist -- I just do
  210. not know them yet.
  211. Architecture and design. How should these components interact? Where do the
  212. delegation boundaries go? I think them through before committing to code.
  213. Consolidation decisions. Should these two skills be merged? Do they serve
  214. distinct purposes, or am I maintaining unnecessary complexity?
  215. Two modes, auto-detected. Quick mode reasons directly. Full mode launches
  216. parallel sub-agents with distinct analytical perspectives, then synthesizes
  217. through agreement patterns.
  218. ```
  219. Use your deepthink skill to think through [question]
  220. ```
  221. For explicit mode selection:
  222. ```
  223. Use your deepthink skill (quick) to [question]
  224. Use your deepthink skill (full) to [question]
  225. ```
  226. ### Refactor
  227. LLM-generated code accumulates technical debt. The LLM does not see duplication
  228. across files or notice god functions growing.
  229. The refactor skill explores multiple dimensions in parallel -- naming,
  230. extraction, types, errors, modules, architecture, abstraction -- validates
  231. findings against evidence, and outputs prioritized recommendations. It does not
  232. generate code; it tells you what to fix and why.
  233. Use it when:
  234. - After LLM-generated features work but feel messy
  235. - Before major changes to identify friction points
  236. - Code review reveals structural issues
  237. - Simple changes require touching many files
  238. ```
  239. Use your refactor skill on src/services/
  240. ```
  241. With focus area:
  242. ```
  243. Use your refactor skill on src/ -- focus on refactoring the rendering engine so that it can be reused in multiple components.
  244. ```
  245. ### Prompt Engineer
  246. This workflow consists entirely of prompts. Each can be optimized individually.
  247. The skill analyzes prompts, proposes changes with explicit pattern attribution,
  248. and waits for your approval before applying anything.
  249. Use it when:
  250. - A sub-agent definition is not performing as expected
  251. - Optimizing a skill's Python script prompts
  252. - Reviewing a multi-prompt workflow for consistency
  253. ```
  254. Use your prompt engineer skill to optimize the system prompt for agents/developer.md
  255. ```
  256. The skill was optimized using itself.
  257. ### Doc Sync
  258. The CLAUDE.md/README.md hierarchy requires maintenance. The structure changes
  259. over time. Documentation drifts.
  260. The doc-sync skill audits and synchronizes documentation across a repository.
  261. Use it when:
  262. - Bootstrapping the workflow on an existing repository
  263. - After major refactors or directory restructuring
  264. - Periodic audits to check for documentation drift
  265. If you use the planning workflow consistently, the technical writer agent
  266. handles documentation as part of execution. Doc-sync is primarily for
  267. bootstrapping or recovery.
  268. ```
  269. Use your doc-sync skill to synchronize documentation across this repository
  270. ```
  271. For targeted updates:
  272. ```
  273. Use your doc-sync skill to update documentation in src/validators/
  274. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.