一种在 LLM 本性之内、用「自然语言 + 目的」设计人机协同工作方式的工程方法。 A human-AI collaboration framework that works with LLM nature, not around it. Built on natural language and purpose — making RAG, agent orchestration, and elaborate prompt engineering unnecessary, not unavailable. Home of the Pang Principle.

📖 网页阅读 / Read on the web:https://huidev2025.github.io/CSF/

AI 辅助开发的主流做法把 LLM 的约束(上下文有限、记忆短、行为不可预测)当作要用技术克服的缺陷——RAG、向量库、Agent 编排、越来越精确的提示词。

CSF 选择另一条路:承认这些约束为事实,在约束内设计。结果是技术栈消失了——不是被替换,是它们的存在理由消失了。

详见引言:引言:你们在拿着前朝的尚方宝剑,斩当朝的官

按顺序,五分钟可以开始:

1. 引言 —— 为什么需要 CSF,乓定律
2. QUICKSTART.md —— 上手指引(中英文):你不需要会代码,只需要把目标说清楚
3. csf-minimal/README.md —— CSF 最小教学版,30 秒说明 + 三个核心差异
4. csf-minimal/context.md —— 你可以直接复制使用的协作记忆模板
5. csf-minimal/体验对比指南.md —— A/B 实验设计,亲自感受差异

想读思想原稿:

6. essays/ — CSF 理论体系连载(6 篇) —— 从公理到定位的完整推导链,深读者送这里

想看 CSF 在真实项目里是什么样子的 / Want to see CSF in action:

7. cases/bang-v3/ — 实战案例:375 次会话节选 —— 三段原始对话日志,展示 AI 拒绝错误决策、自主安排复杂计划、用语义日志快速定位根因的四个具体证据

第一次来? 直接看 QUICKSTART.md 就够了。 First time here? Read QUICKSTART.md first.

两张交互式图谱,帮你在 2 分钟内理解 CSF 在 AI 编程领域的位置:

Two interactive maps to place CSF in the AI-coding landscape — takes about 2 minutes:

csf/
├── README.md # 本文件
├── QUICKSTART.md # 上手指引(中英双栏)
├── LICENSE # CC BY-NC 4.0
├── CONTACT.md # 联系方式(中英双栏)
├── 引言v3:...md # 对外引言(宣言)
├── Manifesto-v3-You-Are-Fighting-the-Wrong-War.md # 英文版宣言
├── assets/ # 对外资源(二维码等)
├── _dlog/ # 公开的真实工作日志(协作示范)
├── cases/ # 实战案例(原始对话日志节选)
├── essays/ # 思想原稿(CSF 理论体系 6 篇连载)
└── csf-minimal/ # 教学最小版
 ├── README.md
 ├── context.md # 给读者用的空白模板
 └── 体验对比指南.md

CSF 不是单一文档,是一套有纵深、已迭代到第三版的体系。按使用门槛与投入深度分三档:

csf-full 是什么:约 60 个核心规程与经验文件构成的工程化人机协作管理系统——四层工程架构(语义管理 / 协作通信 / 质量保障 / 演化系统)+ 三角色协作(Owner / 参谋长 / 开发者)+ W-协议三档质检 + E8 五阶段经验升迁 + D3 三谱系知识路由。

CSF v3 在 不写一行代码、纯文本 的前提下,构建了一个 高内聚、低耦合的软件工程管理系统。其核心由三个工程设计支撑:

行业现状:使用 LLM 时,人必须充当"调度器"——翻 SOP、提醒 AI 该读什么、该用哪个工具,心智负担极重。

CSF v3 的解法:AI 实现了全能力自持。context.md 的"引擎机构"定义了严密的开局协议(L1 加载 → L2 任务级宏观对齐 → L3 具体计划),AI 读完 context.md 自己就知道加载哪些链路、去哪里取资源、如何建立 session-NNN.md 记录、何时校准、何时收尾。控制权从人脑移交给了 AI 的"自我规程"——人的角色从"调度器"压缩为"司令官",只负责确认与纠偏。

行业现状:普通 AI 对话把新旧信息混在一条长聊天记录里,触发"Lost in the Middle"——上下文越长,注意力越涣散。

CSF v3 的解法:在文件系统层面实现冷热分离——

• 基线层(context.md 等,覆写式):永远只保留最新的当前状态。
• Log 层(session-NNN.md,追加式):保留完整讨论过程,需要时回溯。

每次新会话启动,AI 读到的都是"脱水"后的高浓度有用信息,从根上规避了大模型注意力涣散的工程缺陷。

行业现状:CrewAI / AutoGen 这类多 Agent 框架让 AI 之间互相对话——结果是"无限套娃讨论""无效信息轰炸""幻觉互相加强"。

CSF v3 的解法:参谋长(设计态)和开发者(执行态)完全不直接对话。

• 参谋长把设计转化为 STB(任务书),开发者只读 STB,禁止读上游 domain/arch;
• 开发者用三栏自检(✅已读懂 / 🟡不确定 / 🔵准备假设)标记理解状态,任一非空 → PENDING 回参谋长,绝不动键盘;
• 通信通过文件落盘(@MSG:N 哨兵格式),不是对话。

"隔断 + 确定性反馈"是成熟的工业级软件工程思想,被迁移到了 AI 协作场景上:AI 不在对话中互相启动幻觉,人不在跳详中被迫仲裁。

CSF v3 在一个真实双端商业产品的重构项目(微信小程序 + H5 + 云函数后端)中被持续打磨与验证:

Owner 的角色一直停留在"目的与判断"这一层:表达业务真相、校准方向、做价值取舍。架构、分包、设计、编码、测试——CSF 在过程中接管了从"目的"到"可运行代码"之间的全部工程协调。

• CSF 还不能让一个完全不懂软件工程的人独立完成商业产品。Owner 需具备业务判断力与系统性思维,但不需要会写代码。
• CSF 揭示了方法论的可能性,但不表示成熟到可直接使用。并未经历足够多、不同类型项目的实践验证,所以欢迎参与一起完善。
• CSF 并不替代研发团队——它是一套让研发团队的人机协作规范化、质量可控、效率提升的方法。

1. 它能主动建立并跟踪计划 —— 你眼前看到的这个仓库本身(README、Manifesto、CONTACT、_dlog、commit 历史),就是 CSF 在管理它自己的发布过程。
2. 它能在执行中发现问题,回头复查设计、重新制定修复计划并执行到收敛 —— 宣言里给出了具体例子。
3. 极高提升了我个人的设计、开发、测试效率和质量。我不懂代码,不写文档。过程中几次严重的设计缺陷都是我自己偷懒导致的,但也都是AI(或CSF规程)发现并修复的。
4. 计划可以变更,AI在整个过程中有很好的延续性:能抬头看路,也能低头干活儿。

下面这张图,是 AI 在 context.md 中自己维护、给自己(下次开会话的自己)看的项目全景图与当前红点。不是给人看的看板,不是事后整理的汇报材料——是 AI 持续在工作流里写、读、覆写的活产物:

CSF v3 项目全景图与当前任务红点(AI 自维护)

读这张图时,注意几件事:

• 整个项目从 S1 到 M4,主线 + 多次「打岔」(CSF 自身重建、回归试运行、节点统计层、扫描矩阵......)+ 多次计划变更,AI 始终知道自己现在在哪、来自哪、还要去哪——位置、来路、去向三维度全程没有丢。
• "🔴 开发红点 / 参谋红点 / 产出位置" 三行让任意一次新会话零搜索就能续上工作——这正是基线-Log 分离 + 触发索引的工程效果。
• 项目历经数百次会话、跨工作日、跨主题包、跨人机轮转,这张图始终是干净、有结构、可信的——这是 AI 在 CSF 规程之下能稳定持有"项目记忆"的实证。

行业现状对照:当下绝大多数 LLM 工程实践,做不到让 AI 在长周期、多变更、多角色协作中持续维护一份给自己用的、可信的项目状态。CSF 把这件事做出来了。

CSF 体系的 6 个可能的独立创新点已成体系,可单独抽出供研究者参考或者帮我修正:

1. 消费侧 / 供应侧的通用分析框架
2. 目的驱动的注意力工程(不是 prompt engineering)
3. 工程层能力增长独立于模型层 —— 同模型 + 更好的工程组织 → 更好的结果
4. 文件系统作为延伸认知系统(extended cognition)的工程实例
5. D3 三谱系作为知识路由系统
6. 业务语言放大机制(W-协议核心:跨语言翻译会放大误解,业务直觉是检测仪器)

如果你是企业决策者或研发团队负责人,正在为 RAG 复杂度爆炸 / Agent 编排维护成本 / AI 工程化落地困难而困惑——值得读完宣言和 csf-minimal 后联系作者。

CSF is not a single document. It is a layered, third-generation system:

First time here? Start with the Manifesto — why CSF exists, and the Pang Principle (5–10 min read). Then QUICKSTART.md for a hands-on intro. The Visual Guides place CSF in the broader AI-coding landscape in 2 minutes.

What csf-full is: a working set of about 60 core protocol and experience files that constitute an engineering-grade human–AI collaboration management system — a four-layer architecture (semantic management / collaboration / quality / evolution) + a three-role protocol (Owner / Chief-of-Staff / Developer) + the W-protocol (three tiers of verification) + the E8 experience-promotion pipeline + the D3 knowledge-routing system.

In plain text, without a single line of glue code, CSF v3 builds a high-cohesion, low-coupling software-engineering management system on three pillars:

Industry today: humans serve as the scheduler — flipping through SOPs, reminding the LLM what to read next, which tool to invoke. The cognitive load on the human is enormous.

CSF v3: the AI runs itself end-to-end. The "engine" section in context.md defines a strict opening protocol (L1 load → L2 task-level alignment → L3 concrete plan). After reading context.md the AI knows which chains to load, where to retrieve resources, when to log to session-NNN.md, when to recalibrate, and how to close out. Control of "how to collaborate with the human" is handed off from human cognition to the AI's own self-procedure. The human becomes a commander (confirm / correct) rather than a scheduler.

Industry today: in a typical LLM session, fresh and stale information sit side by side in one long transcript — triggering the well-known "Lost in the Middle" attention degradation.

CSF v3: cold/hot separation at the filesystem level —

• Baseline layer (context.md, overwrite-style) keeps only the current dehydrated state.
• Log layer (session-NNN.md, append-only) preserves the full reasoning trail for back-tracing when needed.

Every new session starts from concentrated, current information. The attention-degradation flaw is engineered around, not fought.

Industry today: multi-agent frameworks (CrewAI, AutoGen, ...) let agents chat directly with each other. The common failure modes are "infinite recursion of debate", "noise amplification", and "mutual hallucination reinforcement".

CSF v3: the Chief-of-Staff (design) and the Developer (execution) never converse directly.

• The Chief-of-Staff writes a STB (Simple Task Brief) as the contract. The Developer is forbidden to read upstream domain/ or arch/.
• The Developer self-checks every input through a three-column classifier — ✅ understood / 🟡 unsure / 🔵 working assumption. If any non-✅ remains, the work is PENDING'd back; no keystrokes.
• All cross-role communication happens through the filesystem with a sentinel format (@MSG:N), never as conversation.

"Isolation + deterministic feedback" is mature industrial software engineering applied to the AI-collaboration setting. Agents do not hallucinate at each other in conversation; humans do not get coerced into arbitrating runaway debates.

CSF v3 was hardened inside a real, two-front commercial product refactor (WeChat Mini Program + H5 + cloud-function backend):

The Owner stayed at the level of purpose and judgment throughout — articulating business truth, calibrating direction, making value trade-offs. Architecture, partitioning, design, coding, and testing — CSF coordinated the path from purpose to running code.

• CSF cannot yet let someone with no software-engineering literacy ship a commercial product alone. The Owner needs business judgment and systems thinking — but not coding ability.
• CSF as a methodology is not yet mature. There is substantial work ahead (boundary conditions, degradation modes, experience-aging, the ongoing tension with the LLM training prior, ...).
• CSF does not replace engineering teams. It is a method that makes the team's human–AI collaboration regulated, quality-controllable, and efficient.

1. It can autonomously plan and track work — this very repository (README, Manifesto, CONTACT, _dlog, commit history) is being managed by CSF in front of you.
2. It can detect deviation during execution, loop back to revise design, re-plan the fix, and drive the work to convergence — see the raw dialogue logs in cases/bang-v3/.
3. It dramatically lifted the Owner's design / development / test throughput and quality. The Owner does not write code or docs. Every serious design defect during the project came from the Owner skipping a check — and every one of them was caught and repaired by the AI under the CSF protocol.
4. Plans change. The AI's continuity holds. Across hundreds of sessions and many mid-flight re-plans, the AI consistently knew where it was, where it came from, and where it was going.

The picture below is the project panorama and the current red dot — written, read, and overwritten by the AI inside context.md, for its own next-session self. It is not a dashboard for humans. It is not a post-hoc report. It is a live working artifact.

CSF v3 project panorama and red dot, maintained by the AI itself

Things to notice while reading it:

• The whole project, from S1 through M4, with multiple side-quests (CSF's own rebuild, regression dry-run, node-stats layer, the cross- scan matrix...) and multiple replans — and the AI is always aware of where it is, where it came from, and where it has yet to go.
• The three lines under "current red dot" (Chief-of-Staff red dot / Developer red dot / output location) let any new session pick up the work with zero search. That is the engineering payoff of the baseline–log separation plus the trigger index.
• This artifact survived hundreds of sessions, many workdays, many topic-package transitions, and many human–AI handovers — and remains clean, structured, and trustworthy. That is empirical evidence that an AI under the CSF protocol can hold a faithful "project memory" over the long run.

Compared with the industry status quo, very few LLM workflows produce a durable, AI-authored project state that the AI itself can rely on across long horizons, replans, and role rotations. CSF makes this routine.

cases/bang-v3/ — Real-world case: excerpts from 375 sessions

Three raw AI–Owner dialogue logs from an ongoing commercial project, with four pieces of documented evidence:

1. AI pushes back on a wrong decision — the Owner's original plan was to patch a missing UI component; the AI identified a deeper architectural debt layer, argued against the patch path, and proposed a complete fix instead. The Owner accepted after reading the reasoning.
2. AI acts autonomously within a delegated mandate — instructed to "brief me before executing," the AI independently read the relevant specs, formulated a full execution plan, presented it, and only began modifying files after confirmation.
3. AI self-organizes a complex multi-task plan from a four-word instruction — "make a plan" triggered the AI to scope two inter-dependent workstreams, produce README + progress-table files, and register both in the global project panorama.
4. AI traces root causes across 30 sessions of history — from two semantic log files, without RAG — a timing conflict between two design artefacts (created 30 sessions apart) was identified in minutes by reading their creation timestamps and session numbers, not by searching a vector store.

The logs are unedited. Local file paths in them are not navigable from your machine — that is expected; they are a faithful record of the real session, not a reproducible demo.

The six independent contributions form a self-contained body of work that researchers can engage with on its own terms:

1. The consumer-side vs supply-side analytic frame
2. Purpose-driven attention engineering (not prompt engineering)
3. Engineering-layer capability growth decoupled from the model layer
4. The filesystem as an extended-cognition substrate
5. The D3 knowledge-routing system
6. The business-language amplification mechanism (the W-protocol's core epistemological insight: cross-language translation amplifies misunderstanding; business intuition is the detector)

If you are a decision-maker or engineering leader struggling with runaway RAG complexity, agent-orchestration cost, or stalled AI engineering adoption — read the manifesto and csf-minimal, then reach out.

• 最小教学版(csf-minimal)
• 引言文章(中文 + 英文宣言)
• 发布授权(CC BY-NC 4.0)
• 联系说明(CONTACT.md,中英双栏)
• 小白用户上手指引(QUICKSTART.md,中英双栏)
• csf-lite 公开介绍(不含具体内容)
• 实践案例与社区反馈

我会持续在这个仓库里回答大家的问题(GitHub Issues / 邮件),并在合适的时候整理一些专栏式的长文发布在这里,提供更系统的帮助。如果你有问题,就来问——这是这件事最自然的下一步。

I'll keep answering questions here (GitHub Issues / email) and, when topics deserve it, publish longer column-style essays in this repo for more systematic help. If you have a question, just ask — that is the most natural next step for this work.

由 dapangangang 在 395 次会话的真实重构项目中开发并验证。

• 中文用户:主要落地点是知识星球「一个人走」(含 csf-lite、进阶经验、案例分享,付费社群)。日常反馈走 GitHub Issues,邮箱用于商用咨询。
• English speakers: email is the most direct way; GitHub Issues for public discussion. There's a paid Chinese-language community as an option, but it's Chinese + WeChat-only — email is usually faster.

👉 详细联系方式 / Full contact details:CONTACT.md

邮箱 / Email:dapangangang@gmail.com

如果 CSF 或「乓定律」帮到了你,欢迎复制下面任意一段使用。

一句话引用(中文)

[CSF · 乓定律](https://github.com/huidev2025/CSF) — dapangangang, 2026

One-line citation (English)

[CSF — The Pang Principle](https://github.com/huidev2025/CSF) — dapangangang, 2026

完整引用块

> "The value of AI comes from its intelligence.
> Trying to make it as reliable as a machine is exactly the act of destroying that value."
> — The Pang Principle, dapangangang (CSF, 2026)
> https://github.com/huidev2025/CSF

在你项目的 context.md 末尾(推荐)

<!-- Built with CSF · https://github.com/huidev2025/CSF -->

本仓库的文档与文字内容采用 CC BY-NC 4.0 协议。

• 个人、学术、非营利使用:自由传播、翻译、改编,请保留署名(dapangangang)与原始链接。
• 商业使用(以营利为主要目的的产品、服务、企业内部工具、培训课程、咨询交付物等):请提前联系作者。不一定收费,但希望知道你是谁、用在哪里。
• 创业者:免费。
• 不确定是否算商用:发个 Issue 或邮件问一下就好。

The textual content of this repository is licensed under CC BY-NC 4.0.

• Personal, academic, non-profit use: free to share and adapt with attribution.
• Commercial use requires permission — please reach out. Paid licensing is not the default.
• Startups: free.
• Unsure whether your use is commercial? Open an issue or email dapangangang@gmail.com .

法律上,CC BY-NC 要求署名。但比署名更让我开心的是:

• 用上了,告诉我你在做什么——一个 Issue、一封邮件、社交媒体 @ 一下都行。
• 不是要求,是交朋友。
• 创业者免费;如果它真帮到你,等你跑出来了,记得回来打个招呼。

Legally, CC BY-NC asks for attribution. What I'd actually love more:

• If you use it, tell me what you're building — an issue, an email, a social-media @ all work.
• Not a requirement. Just to stay in touch.
• Startups are free; if it ends up helping you, come say hi when you've made it.

联系 / Contact: see CONTACT.md · dapangangang@gmail.com · GitHub Issues

✍️ 署名说明 / A note on authorship

本仓库的文章,我习惯署名为 by dapangangang with AI。 虽然作者是两位,通讯作者只有我—— AI 很健忘,你知道的 :)

Articles in this repo are signed by dapangangang with AI. Two authors, one corresponding author — the AI is, well, famously forgetful :)