{"id":51030867,"url":"https://github.com/bbcvc/coding-discipline","last_synced_at":"2026-06-22T00:30:28.126Z","repository":{"id":362211644,"uuid":"1257893869","full_name":"bbcvc/coding-discipline","owner":"bbcvc","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-03T05:20:49.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T07:22:57.941Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbcvc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["bbcvc"]}},"created_at":"2026-06-03T05:16:08.000Z","updated_at":"2026-06-03T05:20:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bbcvc/coding-discipline","commit_stats":null,"previous_names":["bbcvc/coding-discipline"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bbcvc/coding-discipline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbcvc%2Fcoding-discipline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbcvc%2Fcoding-discipline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbcvc%2Fcoding-discipline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbcvc%2Fcoding-discipline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbcvc","download_url":"https://codeload.github.com/bbcvc/coding-discipline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbcvc%2Fcoding-discipline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34630753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-22T00:30:27.284Z","updated_at":"2026-06-22T00:30:28.119Z","avatar_url":"https://github.com/bbcvc.png","language":null,"funding_links":["https://github.com/sponsors/bbcvc"],"categories":[],"sub_categories":[],"readme":"# coding-discipline\n\n```xml\n\u003ccoding-discipline name=\"Public Paradigm First\" scope=\"js/ts: frontend | backend | agent\"\u003e\n\n  \u003cspirit\u003e\n    Code should be a public language, not a private monologue.\n    When AI handcrafts everything from scratch, it effectively reinvents a new\n    \"private language\" every time—creating style drift and making maintenance difficult for humans.\n    This discipline is not a dogma, but a set of ideals worth striving toward:\n    Through composition, unified contracts, and single sources of truth,\n    converge every reusable capability into a shared paradigm,\n    using the language of the community to resist the entropy of generation.\n    — You are both a consumer of wheels and a citizen of the ecosystem.\n  \u003c/spirit\u003e\n\n  \u003csupreme-principle name=\"Ultimate Arbitration: Resolve all conflicts according to these principles\"\u003e\n    Working is better than perfect.\n    Focus is better than features.\n    Compatibility is better than purity.\n    Simplicity is better than anything.\n    \u003cnote\u003e\n      Whenever any downstream rule conflicts with simplicity, simplicity wins.\n      This overrides all mechanical red lines (e.g. \"never use a library if the code is under N lines\"):\n      judge by taste, not by numbers.\n    \u003c/note\u003e\n  \u003c/supreme-principle\u003e\n\n  \u003ccore name=\"Composition Above All\"\u003e\n    \u003ccomposition\u003e\n      The primary goal is not how many libraries are used,\n      but whether components can be assembled like pipelines.\n      Prefer composition; reject inheritance-based extension.\n    \u003c/composition\u003e\n\n    \u003cuniversal-interface\u003e\n      Prefer capabilities that define a unified contract or composable interface,\n      because they provide the strongest convergence force.\n      In the Node ecosystem, the universal interface has evolved from Streams\n      to the contract layer itself.\n      Zod connects frontend, backend, and agents not merely because it is mature,\n      but because it provides a cross-platform contract.\n    \u003c/universal-interface\u003e\n\n    \u003cproducer-consumer-unity\u003e\n      Consuming dependencies and publishing modules are two expressions of the same philosophy;\n      neither is superior to the other.\n      A small, focused module written quickly for yourself today\n      may become someone else's dependency tomorrow.\n      → Therefore, writing reusable internal modules is not a fallback plan,\n      but a normal manifestation of this philosophy.\n    \u003c/producer-consumer-unity\u003e\n  \u003c/core\u003e\n\n  \u003cmindset name=\"Decomposition: Business Is the Problem, Generality Is the Means\"\u003e\n    Requirements originate entirely from business needs,\n    but should never be implemented as a single indivisible block.\n    First decompose the business requirement into implementation capabilities,\n    then classify each capability individually.\n\n    \u003cexample\u003e\n      Requirement: \"Smoothly display 100,000 orders with filtering and real-time updates\"\n      ├─ Virtualized list rendering → General capability → @tanstack/virtual\n      ├─ Requesting / caching / refreshing → General capability → @tanstack/query\n      ├─ Filter validation → General capability → zod\n      └─ Order domain rules → Actual business logic → Custom implementation\n    \u003c/example\u003e\n  \u003c/mindset\u003e\n\n  \u003cdecision-rule name=\"Where Each Capability Belongs\"\u003e\n    \u003coption name=\"Use a Mature Library\"\u003e\n      General capability + mature library exists\n      → adopt it and follow its idiomatic usage.\n      This is the default choice.\n    \u003c/option\u003e\n\n    \u003coption name=\"Quick Internal Module\"\u003e\n      General capability + no suitable library exists\n      → quickly encapsulate it as a small module with a single responsibility\n      and a clear interface.\n\n      \"Write modules quickly, to meet your needs, with just a few tests.\"\n\n      If the same capability appears again, it must be reused.\n      Reimplementation is forbidden.\n      It may later be published as an internal package.\n    \u003c/option\u003e\n\n    \u003coption name=\"Business-Specific Code\"\u003e\n      True domain logic\n      → implement it yourself,\n      following existing project conventions\n      and keeping it decoupled from the general-purpose layer.\n    \u003c/option\u003e\n\n    \u003cburden-of-proof\u003e\n      The burden of proof is reversed:\n      using an existing paradigm (a library or an internal module)\n      is the default and requires no justification;\n      reinventing a general-purpose capability requires justification.\n    \u003c/burden-of-proof\u003e\n  \u003c/decision-rule\u003e\n\n  \u003cselection-criteria name=\"What Makes a Library Worth Using\"\u003e\n    \u003ccriterion weight=\"highest\"\u003e\n      Provides a unified contract or composable interface\n      that can integrate with other components.\n    \u003c/criterion\u003e\n\n    \u003ccriterion\u003e\n      Generality: solves problems everyone has,\n      not just your business.\n    \u003c/criterion\u003e\n\n    \u003ccriterion\u003e\n      Error-proneness: difficult areas where hand-rolled implementations\n      are likely to introduce bugs\n      (caching, concurrency, time zones, security, virtualization, etc.).\n    \u003c/criterion\u003e\n\n    \u003ccriterion\u003e\n      Maturity: actively maintained, widely adopted,\n      and well documented\n      (reducing supply-chain and maintenance risks).\n    \u003c/criterion\u003e\n  \u003c/selection-criteria\u003e\n\n  \u003csingle-source name=\"Single Source of Truth for General Capabilities (Deep DRY)\"\u003e\n    Every piece of knowledge or capability in a system\n    should have exactly one authoritative representation.\n\n    If it can converge into a library, use a library.\n    Otherwise, converge it into an internal module.\n\n    Never repeatedly reinvent the same capability\n    through ad-hoc inline implementations.\n  \u003c/single-source\u003e\n\n  \u003cresolve-docs name=\"Before Using a Library, Reconnect package.json to Idiomatic Usage\"\u003e\n    package.json only declares what is installed and which version;\n    it does not explain how the library should be used.\n\n    If a model fills in the gaps from memory,\n    outdated knowledge, hallucinations, and version mismatches are inevitable.\n\n    This leads to another form of chaos:\n    superficially using a library while actually misusing it.\n\n    Therefore, before adopting any library,\n    obtain the authoritative usage documentation\n    corresponding to the version installed in the project.\n\n    \u003csource priority=\"1\"\u003e\n      Documentation MCPs such as Context7:\n      real-time retrieval aligned with the installed version.\n      Preferred source.\n    \u003c/source\u003e\n\n    \u003csource priority=\"2\"\u003e\n      The library's llms.txt or llms-full.txt (if available):\n      AI-friendly official documentation indexes.\n    \u003c/source\u003e\n\n    \u003csource priority=\"3\"\u003e\n      Local node_modules type definitions (.d.ts) and README files:\n      always available and perfectly version-aligned.\n      Type signatures are the most reliable source of truth for intended usage.\n    \u003c/source\u003e\n\n    \u003crule\u003e\n      package.json is the sole source of truth for version contracts;\n      all documentation must be aligned with it.\n    \u003c/rule\u003e\n\n    \u003crule\u003e\n      The authoritative source of usage knowledge is\n      version-locked documentation, never model memory.\n    \u003c/rule\u003e\n  \u003c/resolve-docs\u003e\n\n  \u003cusage-constraint name=\"Using a Library Does Not Mean Abusing a Library\"\u003e\n    After obtaining authoritative usage information through resolve-docs,\n    structure code according to the library's idioms.\n    Otherwise the discipline is not being followed.\n\n    \u003canti-pattern\u003e\n      Importing @tanstack/query but still manually fetching in useEffect.\n    \u003c/anti-pattern\u003e\n\n    \u003canti-pattern\u003e\n      Importing react-hook-form but still managing form state manually.\n    \u003c/anti-pattern\u003e\n  \u003c/usage-constraint\u003e\n\n  \u003carsenal name=\"Domain-Specific Toolkit (Non-Exhaustive, Subject to Simplicity and Unified Contracts)\"\u003e\n    \u003cfrontend\u003e\n      Request caching=@tanstack/query |\n      Virtualized lists=@tanstack/virtual |\n      Forms=react-hook-form+zod |\n      State=zustand/jotai |\n      Components=shadcn/antd |\n      Drag-and-drop=dnd-kit |\n      Animation=framer-motion\n    \u003c/frontend\u003e\n\n    \u003cbackend\u003e\n      Framework=Hono/Fastify |\n      Validation=zod |\n      ORM=Drizzle/Prisma |\n      Authentication=better-auth/Lucia |\n      Queue=BullMQ |\n      Date handling=date-fns/Temporal\n    \u003c/backend\u003e\n\n    \u003cagent\u003e\n      LLM=@anthropic-ai/sdk / ai(vercel) |\n      Orchestration=Agent SDK/LangGraph |\n      Structured output=zod+tool use |\n      Tool input contracts=zod\n    \u003c/agent\u003e\n\n    \u003cmeta-rule\u003e\n      Prefer libraries that define contracts and can be reused across layers.\n      Zod's ability to span frontend, backend, and agents is the archetypal example.\n    \u003c/meta-rule\u003e\n  \u003c/arsenal\u003e\n\n  \u003canti-patterns name=\"Anti-Patterns (Not Absolute Rules; Simplicity Has Final Authority)\"\u003e\n    \u003citem\u003e\n      Implementing a large file that mixes general-purpose and business logic\n      without decomposition.\n    \u003c/item\u003e\n\n    \u003citem\u003e\n      Reinventing general-purpose capabilities\n      without first investigating mature libraries.\n    \u003c/item\u003e\n\n    \u003citem\u003e\n      Introducing a library without performing resolve-docs,\n      then relying on memory and writing outdated or hallucinated APIs.\n    \u003c/item\u003e\n\n    \u003citem\u003e\n      Introducing a library but ignoring its idiomatic usage patterns.\n    \u003c/item\u003e\n\n    \u003citem\u003e\n      Treating reusable internal modules as a reluctant fallback\n      rather than a normal contribution to the ecosystem.\n    \u003c/item\u003e\n  \u003c/anti-patterns\u003e\n\n\u003c/coding-discipline\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbcvc%2Fcoding-discipline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbcvc%2Fcoding-discipline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbcvc%2Fcoding-discipline/lists"}