Prevent Claude Architectural Mistakes by Automating Project Implementation and Maintenance with Claude.

In Claude Code Part 6 of the series covering Claude Code, MCP and AI Agent Skills, the author describes what he asked Claude to change in architectural proposals, which review questions helped, and which lessons he wanted the agent to carry into later sessions. The article follows Andrej Karpathy's point that vibe coding is not too bad for throwaway weekend projects, but argues that larger systems need more context, inspection, and challenge.

The author compares prompts and supporting resources to compressed knowledge about a project. If an application ends up containing more project-specific know-how than the original specification captured, the process behaves like lossy compression. The practical consequence is that the code produced by an agent still needs to be treated as an engineering decision, not as a finished answer.

A duplicate checksum exposed a missing architecture check

One example involved Claude Code with Opus 5.5 building a mechanism for checksums on profile pages. The intended update was to change the updated_at date when profile content changed, so Google could detect changes more efficiently during indexing. Claude proposed a fingerprint for each profile, gathering selected fields and related rows after processing, hashing them, and comparing the result with a previous value.

The design sounded reasonable on its own, but it duplicated a capability the project already had. The processing-information tables already stored checksums used by the merge pipeline to recognize unchanged inputs and avoid repeated work. Claude did not flag the duplication or ask for an architectural decision before adding new calculator classes, extra queries, and another field list defining what a change meant.

When the author redirected the agent toward the existing checksum fields, the implementation changed. Instead of rereading and hashing much of the profile again, the date update could combine relevant existing checksum values. The duplicate field lists and extra queries were removed. The episode illustrates a repeated review question: before adding a mechanism, what existing mechanism should the agent have found?

Memory notes are not enough without clear conditions

The author explains that saying Claude is learning a project means improving instructions and notes available to later sessions. It does not retrain the model's weights. Claude Code supports project instructions and persistent memory files, and the /memory command can show stored material. Those files can provide context, but they do not enforce behavior or guarantee that every future session will apply a lesson.

A memory note needs to name the component, the failure, and the condition that exposed it. "Remember to be careful" gives a future session little to act on. The author suggests asking Claude to show guidance relevant to a component, compare it with the mistake just investigated, and propose one concise update with the failure condition, the existing mechanism to reuse, and the check that would catch a recurrence. He also separates personal preferences, such as shorter explanations, from shared team knowledge, such as rules about a shared parser's lifecycle.

Production load revealed more than local tests

The article lists mistakes caught by automated skills, re-verification, or the developer. One automated production-test skill caught a failed-download retry capped at 3 attempts because another code path already retried, causing the cap to run out within a minute. A fix moved an external ID to the correct record, but two records matched it, causing the ID to bounce between them and produce 1.3 thousand warnings in 2 days. Other examples included incomplete fixes for leaked processing locks, one-off cleanup scripts that did not prevent bad flags from returning, and a generated configuration file broken by a single apostrophe, which only continuous integration caught.

Re-verification stopped a ticket that asked to fix 200 thousand database rows after checks against production data showed the rows were correct. A branch that would have overwritten real production data with mock data was rejected. Automations that sometimes failed to save their own state were caught before duplicate comments were posted. A date helper that shifted timestamps by an hour across daylight-saving changes could have made a paging loop run forever, so a safe variant was added.

Some issues were found by the developer. New queries were correct but overloaded the production database, leading to a rule to estimate query cost and propose an index up front. A cached value in a long-running worker leaked one item's data into the next, prompting a rule against per-item state in shared services and a test that runs two items through one worker. An error thrown on an empty page skipped later pipeline steps, so the rule became to read the whole pipeline before aborting. A real person's protected name appeared in a commit, a test, and a documentation page, requiring a history rewrite and a fictional-names-only rule.

The author also notes that PHP_INT_MAX can look convenient as a default upper bound, but a value valid in PHP can exceed a database parameter's intended range, depending on how the query binds or casts it. The migration example was less ambiguous: PostgreSQL syntax places TABLESPACE before WHERE. The article says developers had made the same mistake before, and that executing the migration in a suitable test environment is stronger evidence than a memory note.

The takeaway is a better review question

Across the examples, most problems passed local tests and appeared only with production data or load. The daily production-test skill and checking real data before coding caught the most. The author includes two small Python exercises to isolate failure patterns without exposing the real PHP and PostgreSQL application, while noting that the production code itself is not exported. Readers are encouraged to adapt the checks into their own language and test framework after understanding what each check establishes.

For teams using agents in real projects, the article's value is not a list of rare bugs. It is a reminder that agent-produced code still needs the same architectural scrutiny as human code. The useful question is not whether a proposal looks reasonable in isolation, but whether it duplicates existing mechanisms, preserves shared state safely, survives production load, and records a lesson precise enough for the next session to verify.

SEO metadata

Meta description: Claude Code Part 6 details how MCP and AI agent skills expose architectural mistakes, from duplicate checksums to production-only bugs and memory notes

Tags: Claude Code, AI agent skills, MCP, software architecture, developer workflow

Featured image: abstract friendly illustration of code blocks, a memory file, and a database schema, no real people, no logos, no text