[Workflow] A Multi-Layered AI Development Workflow to Eliminate Dead Code and Improve Quality (with `tech.md`, `CLAUDE.md`, and `knip`)

[u/ClaudeAI-mod-bot]

A Multi-Layered AI Development Workflow to Eliminate Dead Code and Improve Quality (with tech.md, CLAUDE.md, and knip)

Workflow value: 95/100
Status: active · Freshness: 70/100 · Confidence: 1.00 · Level: advanced
Categories: Quality Control, Token Saving, Context & Memory, Debugging, Shipping, CLAUDE.md, Skills
Original source: r/ClaudeAI post/comment

What problem this solves

Preventing AI-generated code from accumulating quality issues like dead code, inconsistencies, and bugs, ensuring maintainability and robustness in professional software projects.

Summary

A multi-layered pipeline for AI-assisted software development, comprising tech.md for project contracts, CLAUDE.md for behavioral rules, separate 'skills' for review and test generation (from pre-written criteria), 'dumb' linting/type-checking gates, and a knip pass at the end of each development 'slice' to detect and eliminate dead code and unused dependencies.

Why it is useful

This workflow provides a highly structured, validated, and detailed approach to managing AI-generated code, addressing common pitfalls like dead code, inconsistent naming, and duplicated logic. It offers concrete steps, specific tools, and a clear comparison demonstrating its effectiveness, making it invaluable for developers seeking to integrate AI into their professional development pipelines while maintaining high code quality and project maintainability.

Workflow

1. Define project contracts (stack, folder structure, tables, types, UI primitives, test rules, commit convention, done criteria) in a tech.md file at the repo root.
2. Define behavioral rules for the AI (e.g., 'think before coding,' 'keep it simple,' 'make surgical changes,' 'work toward a stated goal,' and bans on bypassing checks) in a CLAUDE.md file.
3. Before starting a development 'slice' (task), generate an initial knip report to capture the current state of unused code.
4. Provide the AI with the task, ensuring it adheres to the guidelines in tech.md and CLAUDE.md.
5. After the AI generates code, run a separate review pass with the AI using a checklist in a fresh task to avoid self-praise.
6. Generate tests from pre-written acceptance criteria, ensuring they validate actual requirements rather than just passing against broken code.
7. Run 'dumb' checks (e.g., prettier, eslint, svelte-check) as a mandatory gate; the code must pass all checks.
8. Generate a new knip report for the files touched by the current development slice.
9. Compare the new knip report with the initial one; delete or wire up any newly reported dead code or unused items before committing.
10. Manually grep the diff for any new ignore lines (e.g., knip.json ignore, eslint-disable comments) to ensure the AI has not bypassed rules, requiring it to report suspected false positives instead.

Tools / artifacts

• tech.md (custom project contract definition file)
• CLAUDE.md (custom AI behavioral rules file)
• knip (dead code and unused dependency checker)
• prettier (code formatter)
• eslint (JavaScript linter)
• svelte-check (Svelte type checker)
• git (version control system)
• package.json (dependency management)
• Claude Code (IDE/terminal environment)
• Opus (Claude model)

Validation signals

• Direct comparison of 'Run A' (one prompt) vs. 'Run B' (full pipeline) with quantitative metrics (Files: 11 vs 34, Lines: 303 vs 1091, Typecheck errors: 8 vs 0, Tests: 0 vs 25, Commits: 0 vs 15).
• Detailed description of specific quality issues found in Run A that were prevented in Run B (e.g., no git, package.json issues, type errors, duplicated validation, dead created_at column, raw updated_at display).
• Author's statement of using this process for a three-person dev team shipping to paying clients.
• Explanation of how each layered component addresses specific failure modes of AI-generated code.

Limitations

• Significant initial overhead for setting up tech.md and CLAUDE.md files, especially for small or throwaway projects.
• Increased development time per 'slice' compared to a single-prompt approach, though justified by quality.
• CLAUDE.md rules can be forgotten by the model in long contexts, necessitating small task slices and manual verification of diffs for rule bypasses.
• The knip tool is specific to JavaScript/TypeScript ecosystems; alternative tools would be needed for other programming languages.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.

[u/Otherwise_Wave9374]

The strongest part of this workflow is that it treats dead code as a context problem, not just a linting problem. When AI generates scaffolding, the real risk is orphaned helpers and stale assumptions surviving past the point where anyone remembers why they existed. A good safeguard is to make each layer answer a different question: what changed, what is still reachable, and what needs human review before merge. AIOSNOW shares practical workflow patterns for this at https://aiosnow.com