b3os-ai-code-safety

b3rys AI Code Safety — Structure & Refactoring

As code and logic grow, the cost is not the happy path — it is coupling: a change ripples into places you did not touch, and a "small fix" breaks something unrelated. This skill is a code-structure and refactoring guide: structure well from the initial design so a change stays local, apply operational safety where effects live, and refactor deliberately when the code smells. (Team-workflow rules — backup-first, verbatim user input, don't-touch-working-logic — live in TEAM-OS, not here.)

Two throughlines:

• Structure to reduce side effects and coupling — so most changes stay in one place.
• Refactor when it smells — the "I fixed one thing and something unrelated broke" signal is coupling telling you where the structure is wrong.

Phase 1 — Design (structure before writing)

• Data flow / source of truth first. Map read → transform → write, and name the single source of truth for each piece of state. Confirm you read the live source, not a synced mirror that drops fields. (Example: reading a synced copy that lacks a field compiles and passes unit tests, but the output is wrong.)
• SOLID as coupling design, not class patterns. (SOLID = five object-oriented design principles; here we use them as a low-coupling lens, not a class-pattern checklist.) Dependencies point inward — domain/use-case logic does not depend on framework/ORM/HTTP/infra (DIP, dependency inversion: depend on an abstraction, not a concrete infra type). One reason to change per module (SRP, single responsibility). Depend on the small slice you actually use (ISP, interface segregation: small interfaces). Add an abstraction only when a real extension axis exists (skip speculative OCP, open/closed).
• Module boundaries hide volatile decisions. A module's public contract is a schema/interface/event/API; its private choices (storage, format, algorithm) stay hidden and swappable. One owner per concern — no two modules writing the same mutable state.
• 서버·클라이언트 역할 분리. 서버는 상태(코드)와 데이터를 주고, 클라이언트는 그것을 문장·아이콘·UI 로 보여 준다. 서버가 화면에 보일 문장을 만들면 문구 하나 바꿀 때마다 서버를 고치게 된다. 사람이 읽는 문장·튜닝 숫자·AI 지시문은 코드에 넣지 않고 문구·설정 파일로 분리한다 — 그래야 문구를 고치거나 다른 언어를 추가할 때 코드를 수정하지 않고, 화면을 언어마다 따로 만들지 않는다. 100% 원칙은 아니다 — 디버깅 로그처럼 개발자만 보는 문장 등 필요한 경우는 코드에 둘 수 있다.
• Start simple; restructure when a change starts causing side effects — not up front. The criterion is not size: it is whether one class or function has taken on so many jobs that changing one breaks another. With few features, don't layer in advance. Watch these, cheapest first:
  • Cross-area direct writes (primary): count how many areas write the same shared field. A guard test fails if the count goes up; the target is one entry point per field.
  • A mutant in one area fails another area's tests (primary): that is a side-effect coupling point — split there.
  • A state judged from three or more fields combined by ifs → one state value + one reduce(state, event) → (state, effects) table; every cell written, an empty cell fails a test.
  • Line count of a file or function (signal only): report it, don't fail on it. A very long function or a file with many unrelated sections is where to look first.
• Don't take the first design when it is expensive to reverse. For a data shape, a storage or wire format, a public API, or a new UI interaction with no precedent in the codebase, get 2–3 independent candidates (a different model family when available) or build small runnable prototypes and compare them side by side. Write the caller's usage first in each candidate. Answer open questions by running a prototype, not by debate, and review a plan only after code has answered its open questions — a plan with no code behind it draws invented risks. A design judgment (refactor or not, where a shared rule lives, the direction of a large fix) goes to a read-only architect review first, and the question always includes "is this necessary? is it over-engineering?"; report the verdict with the dissent. Most changes need none of this.
• For code other code will call, write the usage doc first. A short README or example of how a caller uses the new package or API sets the target and forces the caller's view.