Praise: Spot on with identifying the risk of "silent decisions." In AI-driven development, state drift and hidden technical debt compound rapidly because LLMs default to greedy token selection pathways that maximize immediate plausibility over long-term architectural coherence. Explicitly enforcing a CLAUDE.md to break the agent out of its default "hallucinate-and-patch" loop is an excellent way to reclaim deterministic control over design patterns and maintain dependency boundaries.
Critique: While prototyping logic via throwaway HTML click-throughs works for high-level business flows, it introduces a dangerous abstraction leak for performance, concurrent state synchronization, or low-level API design. A more robust, automation-friendly alternative is pushing the model to generate a strict OpenAPI spec, an ASCII state-machine diagram, or a comprehensive suite of behavior-driven development (BDD) integration tests prior to writing production code. This catches edge cases deterministically and scales better than manual visual verification.
I agree that API design and integration testing are critical. Should be a separate rule on their own. If you can take a stab at the rule and share, we can incorporate it.
- Do not generate business logic, internal functions, or UI wrappers until the system boundary contract is explicitly defined and approved.
- Force all interface designs into strict, declarative schemas before implementation:
- For HTTP/REST: OpenAPI specs.
- For Event-Driven/Queues: AsyncAPI schemas.
- For Internal Modules: ASCII state machines or strongly typed interface signatures.
- Validation Rule: All subsequent code generation must be deterministically checked against the agreed contract. Write behavior-driven development (BDD) integration tests alongside the schema to catch edge cases, state synchronization failures, and payload drift before runtime.
Praise: Spot on with identifying the risk of "silent decisions." In AI-driven development, state drift and hidden technical debt compound rapidly because LLMs default to greedy token selection pathways that maximize immediate plausibility over long-term architectural coherence. Explicitly enforcing a CLAUDE.md to break the agent out of its default "hallucinate-and-patch" loop is an excellent way to reclaim deterministic control over design patterns and maintain dependency boundaries.
Critique: While prototyping logic via throwaway HTML click-throughs works for high-level business flows, it introduces a dangerous abstraction leak for performance, concurrent state synchronization, or low-level API design. A more robust, automation-friendly alternative is pushing the model to generate a strict OpenAPI spec, an ASCII state-machine diagram, or a comprehensive suite of behavior-driven development (BDD) integration tests prior to writing production code. This catches edge cases deterministically and scales better than manual visual verification.
I agree that API design and integration testing are critical. Should be a separate rule on their own. If you can take a stab at the rule and share, we can incorporate it.
Contract-First Development (APIs Over UIs)
- Do not generate business logic, internal functions, or UI wrappers until the system boundary contract is explicitly defined and approved.
- Force all interface designs into strict, declarative schemas before implementation:
- For HTTP/REST: OpenAPI specs.
- For Event-Driven/Queues: AsyncAPI schemas.
- For Internal Modules: ASCII state machines or strongly typed interface signatures.
- Validation Rule: All subsequent code generation must be deterministically checked against the agreed contract. Write behavior-driven development (BDD) integration tests alongside the schema to catch edge cases, state synchronization failures, and payload drift before runtime.