Write code like a human will maintain it
353 points
• 7 days ago
• Article
Link
使用大型语言模型生成代码虽然方便，但容易让人对技术债务产生错误的安全感。为了追求速度，开发者常常依赖 AI 在多个文件间复制逻辑，而不是抽出共享的 helper 或实现可重用的模式。因为 AI 能持续产出通过测试的可运行代码，开发者就更容易放松对整洁、遵循避免重复（DRY）原则代码的要求，认为未来的修改交给模型就能解决。
但这种想法忽视了一个事实：大型语言模型是通过分析现有代码库来生成输出的。每一处捷径或糟糕实现被合并进项目，都会成为模型的训练信号，教它把这些冗余或混乱的模式当作仓库的常规做法。你让 AI 写新功能时，它不会去寻找最优雅的架构，而是照搬已有文件里的模式。
这会形成一个危险的反馈循环：技术债务不仅被积累，还被不断强化。一旦在多个地方出现了次优的实现，模型在被要求生成类似接口或函数时就会如实复现这些做法。即便开发者后来想要重构，AI 也很可能保留这些坏习惯，把它们当作代码库的基础风格，而不是需要清理的技术债务。
把维护工作外包给 AI 的讽刺之处在于，这个过程通常会逐渐降低代码库的质量，直到即便有自动化辅助也难以应对。重复的条件判断、臃肿的一体化函数等"代码异味"会迅速堆积，制造出一个复杂且脆弱的环境，使 AI 不再能可靠地解决问题。最终，开发者还是得亲自出手，处理那些本想通过 AI 省掉的手工工作。
与其把 AI 当作替代者，不如把它当作会通过示例学习的协作者。大型语言模型会反映出所接收代码的习惯和质量，因此保持高标准至关重要。像对待未来的人类维护者那样编写代码，能给 AI 传递正确的信号，从而随着时间的推移带来更稳健、更整洁、更可持续的代码库。
The convenience of using Large Language Models to generate code can easily lead to a false sense of security regarding technical debt. It is tempting to prioritize speed, relying on an AI to replicate logic across multiple files rather than spending the time to implement clean, reusable patterns like shared helpers. Because the AI consistently produces functional code that passes tests, developers may feel excused from the traditional discipline of maintaining clean, DRY code, assuming that future modifications will simply be another task for the model to handle.
However, this perspective overlooks the fact that LLMs operate by analyzing the existing codebase to inform their outputs. Every shortcut merged into a project serves as a training signal, teaching the model that these redundant or messy patterns are the accepted standard for the repository. When you ask the AI to generate new features, it does not look for the most elegant architectural solution, it looks at the existing files and replicates the patterns already present.
This creates a dangerous feedback loop where technical debt is not just accumulated, but actively reinforced. Once a suboptimal pattern is established in several locations, the model will faithfully reproduce it every time it is asked to generate a similar endpoint or function. If a developer attempts to request a refactor later, the AI is likely to preserve the bad habits, viewing them as the foundational style of the codebase rather than as technical debt that needs to be resolved.
The irony of outsourcing maintenance to an AI is that the process often degrades the quality of the codebase until it becomes difficult to manage, even with automated assistance. Code smells like duplicated conditionals and monolithic functions quickly stack up, creating a complex environment where the AI can no longer be trusted to resolve issues reliably. Eventually, the developer is forced to step in and perform the manual work they thought they were avoiding in the first place.
Ultimately, the best approach to working with AI tools is to treat them as collaborators that learn by example. Since LLMs act as sponges that mirror the habits and quality of the code they are fed, maintaining a high standard is essential. By writing code as if a human will maintain it, you ensure that the AI receives quality signals, which in turn leads to a more robust, clean, and sustainable codebase over time.
304 comments • Comments Link
- 通过 markdown 清单实现专用 `/review` 命令，作为动态提示，供 agents 在每次重大变更后执行系统性检查、代码清理与重构。
- 指示模型并行扮演多种专责角色（例如 Security Engineer 、 WCAG Specialist），将各自发现汇总成一份综合报告，以增强代码审查效果。
- 维护严格的自动化标准（包括 pre-commit hooks 、静态分析和 CI 作业），以在不依赖 LLM 风格倾向的情况下强制执行代码质量，避免"vibe coding"。
- 通过创建专门的模块化规则文件（例如 `coding_rules.md`），指示 agents 根据具体任务加载相应规则，避免把所有内容堆在单一全局配置里。
- 使用对抗性测试（通过多个模型和多轮审查迭代代码）来发现单次审查常被忽视的细微 bug 和架构问题。
- 关注结构健康度进行重构：模型在大型单体项目上的效率会下降，把代码拆分为隔离、以 API 定义的组件，可以把"基准"复杂度控制在 agent 可管理的范围内。
- 严格审查代码注释，要求解释复杂逻辑的"原因"，剔除进度记录或对代码的简单复述类噪音，以减少认知负担和同步失败。
- 认识到 AI 虽能加快开发速度，但也会引入代码臃肿和不可维护性的风险，需要人类主导的架构监督和持续验证。
- 将 AI 生成的代码视为需人工验证的初稿，以防止代码库被"中毒"，因为 agents 往往倾向于叠加补丁而非从根本上解决问题。
- 在团队环境中应优先人类可维护的代码而非单纯追求速度，承认 AI 是强大的倍增器，但不能替代对可读、结构良好且经过验证系统的长期需求。
AI 在软件开发中的整合已把重心从纯手工编码转向架构与编排。尽管许多人报告生产力显著提升，但共识指出，缺乏严格监督下的"vibe coding"会导致技术债务、代码臃肿和可维护性危机。成功的开发者正越来越多地采用结构化、基于 agent 的工作流，结合自动 linting 、多角色审查和模块化规则集，以确保速度不会以牺牲系统完整性为代价。总体而言，最有效的做法是将 AI 视为强大但易出错的助手，由人类保持纪律、维护清晰抽象，并验证输出以保证未来的可维护性。 • Implement a specialized `/review` command via a markdown checklist, which acts as a dynamic prompt for agents to execute systematic inspections, code cleanup, and refactoring after every significant change.
• Augment code reviews by instructing the model to adopt multiple specific personas (e.g., Security Engineer, WCAG Specialist) in parallel, then synthesizing their findings into a single, comprehensive report.
• Avoid "vibe coding" by maintaining rigorous, automated standards, including pre-commit hooks, static analysis, and CI jobs that enforce code quality independently of the LLM's own stylistic inclinations.
• Move beyond generic instructions by creating specialized, modular rule files (e.g., `coding_rules.md`) that agents are instructed to load based on the specific task, rather than cluttering a single global configuration.
• Use adversarial testing—passing code through multiple models and review iterations—to identify subtle bugs and architectural issues that a single-pass review typically overlooks.
• Refactor codebases by focusing on structural health, as model efficiency degrades on large, monolithic projects; breaking code into isolated, API-defined components keeps the "baseline" complexity manageable for the agent.
• Treat code comments with extreme scrutiny, requiring them to explain the "why" of complex logic while stripping away "progress tracking" noise or restatements of code, which lead to cognitive load and synchronization failures.
• Recognize that while AI accelerates development speed, it introduces significant risks regarding code bloat and unmaintainable complexity that necessitates human-led architectural oversight and continuous validation.
• Address the "poisoning" of codebases by treating AI-generated code as an initial draft that requires human verification, as agents are prone to stacking patches rather than addressing the root causes of issues.
• Prioritize human-maintainable code over raw speed when working in team environments, acknowledging that while AI is a powerful force multiplier, it cannot replace the long-term necessity for readable, well-structured, and verified systems.
The integration of AI into software development has shifted the focus from manual typing to architecture and orchestration. While many report significant gains in productivity, the discussion reveals a clear consensus that "vibe coding"—relying on AI without rigorous oversight—leads to technical debt, code bloat, and maintainability crises. Successful developers are increasingly moving toward structured, agent-based workflows that combine automated linting, multi-persona reviews, and modular rule sets to ensure that speed does not come at the expense of system integrity. Ultimately, the consensus suggests that the most effective approach is to treat the AI as a powerful but fallible assistant, requiring human discipline to maintain clear abstractions and verify that the output remains understandable for future maintenance.