Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bbcvc/coding-discipline


https://github.com/bbcvc/coding-discipline

Last synced: 13 days ago
JSON representation

Awesome Lists containing this project

README 

          
# coding-discipline



```xml



  

    Code should be a public language, not a private monologue.

    When AI handcrafts everything from scratch, it effectively reinvents a new

    "private language" every time—creating style drift and making maintenance difficult for humans.

    This discipline is not a dogma, but a set of ideals worth striving toward:

    Through composition, unified contracts, and single sources of truth,

    converge every reusable capability into a shared paradigm,

    using the language of the community to resist the entropy of generation.

    — You are both a consumer of wheels and a citizen of the ecosystem.

  



  

    Working is better than perfect.

    Focus is better than features.

    Compatibility is better than purity.

    Simplicity is better than anything.

    

      Whenever any downstream rule conflicts with simplicity, simplicity wins.

      This overrides all mechanical red lines (e.g. "never use a library if the code is under N lines"):

      judge by taste, not by numbers.

    

  



  

    

      The primary goal is not how many libraries are used,

      but whether components can be assembled like pipelines.

      Prefer composition; reject inheritance-based extension.

    



    

      Prefer capabilities that define a unified contract or composable interface,

      because they provide the strongest convergence force.

      In the Node ecosystem, the universal interface has evolved from Streams

      to the contract layer itself.

      Zod connects frontend, backend, and agents not merely because it is mature,

      but because it provides a cross-platform contract.

    



    

      Consuming dependencies and publishing modules are two expressions of the same philosophy;

      neither is superior to the other.

      A small, focused module written quickly for yourself today

      may become someone else's dependency tomorrow.

      → Therefore, writing reusable internal modules is not a fallback plan,

      but a normal manifestation of this philosophy.

    

  



  

    Requirements originate entirely from business needs,

    but should never be implemented as a single indivisible block.

    First decompose the business requirement into implementation capabilities,

    then classify each capability individually.



    

      Requirement: "Smoothly display 100,000 orders with filtering and real-time updates"

      ├─ Virtualized list rendering → General capability → @tanstack/virtual

      ├─ Requesting / caching / refreshing → General capability → @tanstack/query

      ├─ Filter validation → General capability → zod

      └─ Order domain rules → Actual business logic → Custom implementation

    

  



  

    

      General capability + mature library exists

      → adopt it and follow its idiomatic usage.

      This is the default choice.

    



    

      General capability + no suitable library exists

      → quickly encapsulate it as a small module with a single responsibility

      and a clear interface.



      "Write modules quickly, to meet your needs, with just a few tests."



      If the same capability appears again, it must be reused.

      Reimplementation is forbidden.

      It may later be published as an internal package.

    



    

      True domain logic

      → implement it yourself,

      following existing project conventions

      and keeping it decoupled from the general-purpose layer.

    



    

      The burden of proof is reversed:

      using an existing paradigm (a library or an internal module)

      is the default and requires no justification;

      reinventing a general-purpose capability requires justification.

    

  



  

    

      Provides a unified contract or composable interface

      that can integrate with other components.

    



    

      Generality: solves problems everyone has,

      not just your business.

    



    

      Error-proneness: difficult areas where hand-rolled implementations

      are likely to introduce bugs

      (caching, concurrency, time zones, security, virtualization, etc.).

    



    

      Maturity: actively maintained, widely adopted,

      and well documented

      (reducing supply-chain and maintenance risks).

    

  



  

    Every piece of knowledge or capability in a system

    should have exactly one authoritative representation.



    If it can converge into a library, use a library.

    Otherwise, converge it into an internal module.



    Never repeatedly reinvent the same capability

    through ad-hoc inline implementations.

  



  

    package.json only declares what is installed and which version;

    it does not explain how the library should be used.



    If a model fills in the gaps from memory,

    outdated knowledge, hallucinations, and version mismatches are inevitable.



    This leads to another form of chaos:

    superficially using a library while actually misusing it.



    Therefore, before adopting any library,

    obtain the authoritative usage documentation

    corresponding to the version installed in the project.



    

      Documentation MCPs such as Context7:

      real-time retrieval aligned with the installed version.

      Preferred source.

    



    

      The library's llms.txt or llms-full.txt (if available):

      AI-friendly official documentation indexes.

    



    

      Local node_modules type definitions (.d.ts) and README files:

      always available and perfectly version-aligned.

      Type signatures are the most reliable source of truth for intended usage.

    



    

      package.json is the sole source of truth for version contracts;

      all documentation must be aligned with it.

    



    

      The authoritative source of usage knowledge is

      version-locked documentation, never model memory.

    

  



  

    After obtaining authoritative usage information through resolve-docs,

    structure code according to the library's idioms.

    Otherwise the discipline is not being followed.



    

      Importing @tanstack/query but still manually fetching in useEffect.

    



    

      Importing react-hook-form but still managing form state manually.

    

  



  

    

      Request caching=@tanstack/query |

      Virtualized lists=@tanstack/virtual |

      Forms=react-hook-form+zod |

      State=zustand/jotai |

      Components=shadcn/antd |

      Drag-and-drop=dnd-kit |

      Animation=framer-motion

    



    

      Framework=Hono/Fastify |

      Validation=zod |

      ORM=Drizzle/Prisma |

      Authentication=better-auth/Lucia |

      Queue=BullMQ |

      Date handling=date-fns/Temporal

    



    

      LLM=@anthropic-ai/sdk / ai(vercel) |

      Orchestration=Agent SDK/LangGraph |

      Structured output=zod+tool use |

      Tool input contracts=zod

    



    

      Prefer libraries that define contracts and can be reused across layers.

      Zod's ability to span frontend, backend, and agents is the archetypal example.

    

  



  

    

      Implementing a large file that mixes general-purpose and business logic

      without decomposition.

    



    

      Reinventing general-purpose capabilities

      without first investigating mature libraries.

    



    

      Introducing a library without performing resolve-docs,

      then relying on memory and writing outdated or hallucinated APIs.

    



    

      Introducing a library but ignoring its idiomatic usage patterns.

    



    

      Treating reusable internal modules as a reluctant fallback

      rather than a normal contribution to the ecosystem.

    

  



```