Skills-Oriented Programming: Domain Knowledge Engineering for Efficient Code Generation by Code Agents

Introduction

AI programming tools are advancing rapidly. Code Agents handle small projects with ease, but they frequently hit walls when facing enterprise-level complex business architectures—context windows run out of space, and fixing one thing breaks another. The Alibaba Mama technical team has proposed a "Skills-Oriented Programming" methodology based on domain knowledge engineering to address this pain point. The core idea is clear: through structured knowledge management and a progressive disclosure mechanism, AI can access precise context even in complex codebases, dramatically improving the accuracy and efficiency of code generation.

The Real Challenges of AI Programming in Complex Business Architectures

Knowledge Gaps Are the Core Pain Point

When codebases balloon to hundreds of thousands of lines, the biggest obstacle AI faces isn't insufficient computing power—it's a complete knowledge gap: the historical logic behind the code is unclear, documentation is severely out of sync with actual code, and key developers have already left the company. Every time AI needs to modify a requirement, humans must re-supply massive amounts of background knowledge, ultimately reducing AI to a "glorified typist" that can't deliver its true value.

It's important to understand the technical positioning and capability boundaries of Code Agents here. A Code Agent refers to an AI programming intelligent agent with capabilities for autonomous planning, tool invocation, and code generation. Typical examples include Cursor Agent, Devin, and OpenHands. Unlike traditional code completion tools (such as early versions of GitHub Copilot), Code Agents can understand natural language requirements, autonomously browse codebases, invoke terminal commands, execute tests, and iteratively fix issues. However, their capability boundaries are highly dependent on the quality of context they can access—in small projects, Agents can quickly build global understanding by traversing files; but in enterprise-level codebases with hundreds of thousands of lines, Agents cannot fit all relevant information within their limited context windows and must rely on external knowledge management mechanisms to compensate for this deficiency.

Codebase Complexity Far Exceeds Expectations

In a codebase of 200,000+ lines, only about 20,000 lines may be actively in use, with the rest being legacy or deprecated logic. The coupling relationships between different business lines are incredibly complex. When AI handles requirement changes, it frequently can't figure out contextual dependencies—"fix this here, and that breaks over there"—ultimately forcing abandonment of automatic generation and complete reliance on human intervention.

Domain Knowledge Engineering: Building an Expert Manual for Code Agents

The root of the problem is that whether it's developers or AI, when facing a massive system without centralized, structured knowledge management, everyone is left to figure things out on their own, making misunderstandings or critical information gaps highly likely.

The core idea of domain knowledge engineering is: centrally organize and structure the fragmented domain knowledge that exists only in certain people's heads, building a "dedicated expert manual." This manual helps developers quickly find information and enables Code Agents to accurately retrieve it, thereby improving the efficiency and quality of the entire development workflow.

Skill Three-Layer Structure and Progressive Disclosure Mechanism Explained

Why Simply Feeding Documents to AI Doesn't Work

The early approach was to dump massive amounts of (often outdated) business documentation into AI all at once. The result? Not only did token counts immediately explode, but AI couldn't grasp the key points at all—accuracy plummeted and attention became extremely scattered. This "information bombardment" approach is virtually unusable in real engineering scenarios.

This involves the engineering bottleneck of context windows and attention mechanisms. While current mainstream large language models (such as GPT-4, Claude, etc.) have expanded their context windows to 128K or even longer tokens, in actual engineering scenarios, window length does not equal effective utilization. Research shows that when input content exceeds a certain length, the model's attention to information in the middle sections drops significantly (the "Lost in the Middle" phenomenon), causing critical information to be overlooked. Additionally, token consumption directly correlates with API call costs—in enterprise-level high-frequency calling scenarios, unrestricted filling of context windows creates enormous cost pressure. This is precisely the core engineering problem that the Skill three-layer structure and progressive disclosure mechanism aims to solve.

Precise Routing and On-Demand Loading of Skills

The core concept of Skills is: instead of giving AI a dictionary, give it a mechanism for precise routing and on-demand loading. Each time, AI only needs to access the portion of knowledge currently required, saving token consumption while making the reasoning process more controllable and efficient.

Each Skill consists of a three-layer structure using a progressive disclosure strategy:

• Summary Layer (~100 words): Always visible, containing the Skill name and brief description, helping the model quickly determine whether it needs to use this Skill
• Body Layer (~3000 words): Loaded only when the model determines it needs deeper understanding, containing business rules, core concepts, main workflows, and change guidelines
• Detail Layer: Loaded only when specific data structures or interface definitions are needed during code generation, including interface specifications, data model definitions, etc.

This design works just like how we look up information: first check the table of contents, then read the abstract, and only flip to the appendix when encountering specific details. This progressive disclosure mechanism ensures the Code Agent processes just the right amount of information at each stage.

AI Reasoning Path Design Based on Domain Knowledge

The entire knowledge system is divided into three levels, guiding Code Agents to think and generate code following a macro-to-micro approach:

Layer 1: Global Project Map

This includes the project's AGENTS.md and rules files (Rules), which tell the AI the overall project structure, glossary, and hard constraints upfront—letting it know "where am I right now" and "what are the rules around here."

It's worth noting that AGENTS.md is an emerging project-level AI configuration file specification, originally promoted by Google in their internal engineering practices, and subsequently adopted as a similar concept by tools like Cursor's .cursorrules and Windsurf's .windsurfrules. Its purpose is to place a structured documentation file in the repository root that tells Code Agents about the project's tech stack, directory structure, coding standards, testing requirements, and other key information. This is essentially giving AI a "project onboarding manual," allowing it to establish a basic cognitive framework of the project before starting work, rather than blindly exploring from scratch.

Layer 2: Skill Main Files

When AI encounters a specific task, it loads the corresponding Skill's main file, which contains the core business logic and key code workflows.

Layer 3: References Details

Only when encountering more granular content (such as interface definitions) does AI enter the references directory to pull specific details.

This reasoning path from global to local to atomic details closely matches how large language models think, avoiding the attention dispersion caused by loading too much information at once.

Explicit Mapping Between Knowledge and Code Workflows

The traditional approach only tells AI what rules exist, leaving AI to guess the correspondence between rules and code—which is highly error-prone. In the Skills-Oriented Programming approach, every rule explicitly specifies its associated workflow, node, and entry point, essentially drawing a navigation map for AI. Through this explicit mapping, code generation accuracy can be raised to over 90%.

Knowledge Anti-Corruption: A Four-Layer Protection System Spanning the Development Lifecycle

Outdated Knowledge Is More Dangerous Than No Knowledge

Code Agents blindly trust rules when generating code. Once they use outdated or incorrect information, they rapidly replicate that error throughout the entire codebase. And code changes far faster than knowledge updates—if not addressed promptly, the entire system will quickly deteriorate from incorrect rules.

Knowledge Rot is actually a classic challenge in software engineering, referring to the phenomenon where documentation, comments, wikis, and other knowledge carriers gradually drift out of sync with actual code. According to Stack Overflow's developer survey, over 60% of developers believe internal documentation is "frequently or always outdated." In traditional development, the consequence of knowledge rot is mainly increased onboarding costs and communication overhead; but in the AI programming era, this problem is dramatically amplified—Code Agents treat outdated rules as "truth" and strictly execute them, with errors spreading throughout the codebase at the speed of code generation, causing damage far beyond what manual coding could inflict.

Four-Layer Protection Ensures Continuously Accurate Knowledge

The team built a four-layer protection system spanning the entire development lifecycle:

1. Reverse Verification: When AI reads knowledge or code and detects inconsistencies between the two, it automatically generates correction suggestions
2. Communication Supplementation: When AI encounters something it doesn't understand, it proactively discusses with developers, then summarizes the discussion results and updates the knowledge base directly
3. Commit Verification: Every code commit is subject to mandatory checks—any code change must include corresponding knowledge updates to prevent new corruption from entering
4. Full Audit: After each release, a global comparison is performed across the entire codebase and knowledge base to ensure nothing is missed

Through this mechanism, documentation updates become a natural part of the development process, eliminating the need for dedicated manual maintenance.

Domain Scale vs SDD: A Fundamental Shift in AI Programming Development Paradigms

Traditional SDD (Spec-Driven Development) works well for brand-new projects, but in daily small iterations, the cost of writing Specs far exceeds directly writing code, and these Specs are essentially one-time-use artifacts that rarely accumulate into anything valuable.

Some additional background on SDD is warranted here. SDD (Spec-Driven Development) is a development paradigm that has gained popularity alongside the rise of AI programming tools. Its core idea is to write detailed technical specification documents (Specs) in natural language before writing code, then have AI generate code based on the Specs. This approach works remarkably well for greenfield projects or initial development of large feature modules, as Specs provide AI with clear requirement boundaries and technical constraints. However, in daily iterations, a small requirement might only involve modifying a few lines of code but requires spending several times more effort writing and maintaining a Spec—a severely imbalanced input-output ratio. More critically, these Specs are typically oriented toward single tasks and lose their value once the task is complete, unable to accumulate into reusable team knowledge assets.

Domain Scale (domain knowledge-driven development) emphasizes maintaining a continuously growing body of core domain business knowledge. This knowledge base becomes richer as the project progresses and represents a true team asset. Every new piece of code written is a physical implementation of that knowledge, continuously accumulating compound returns rather than creating "disposable utensils" that get thrown away after each use.

Future Competitiveness: Domain Knowledge Is the Moat in the AI Programming Era

As large model capabilities continue to improve, general-purpose AI programming toolchains will evolve very quickly. The key factor determining whether a team can stand out in the future will no longer be who has better tools, but rather:

• Whether you possess a continuously updated domain knowledge system
• Whether you have dedicated MCP tools built specifically for Code Agents
• Whether you have a clean, well-structured proprietary code repository

The MCP (Model Context Protocol) mentioned here is an open standard protocol proposed by Anthropic, designed to provide large language models with a unified way to access external tools and data sources. Through MCP, Code Agents can access databases, search engines, internal knowledge bases, and other external resources as easily as calling an API, without needing to stuff all information into the context window. In the context of domain knowledge engineering, dedicated MCP tools mean teams can package their Skill knowledge bases, code indexes, and business rule engines as MCP services, allowing any AI tool compatible with the MCP protocol to seamlessly integrate, thereby achieving standardized distribution and reuse of knowledge.

Teams shouldn't obsess over building their own underlying AI toolchains. Instead, they should focus their energy on turning domain knowledge into a competitive barrier, selecting the scenarios best suited for business closed-loops for deep customization and optimization.

Practical Implementation Recommendations

1. Assess business suitability first: Confirm whether the business operates in a closed loop and whether domain knowledge can be comprehensively enumerated
2. Start with small-scale pilots: Begin with the modules that change most frequently or have the most obvious pain points—this allows you to see results quickly while keeping risk manageable
3. Establish protection mechanisms first: Make sure to set up Commit verification as a gate first—process safeguards take priority over documentation completeness. Otherwise, technical debt easily accumulates, and things get messier over time

Conclusion

Skills-Oriented Programming through domain knowledge engineering essentially builds a structured bridge between AI and complex business code. Through the progressively disclosed Skill three-layer design, the macro-to-micro reasoning path, explicit mapping between knowledge and code, and the four-layer knowledge anti-corruption system, Code Agents gain the genuine ability to understand and handle complex business logic. In an era where AI programming tools are increasingly commoditized, deeply investing in domain knowledge engineering is the key to building a team's long-term technical moat.

Key Takeaways

• Skills employ a progressive disclosure mechanism (summary → body → detail three-layer structure), enabling precise routing and on-demand loading that dramatically saves token consumption while improving AI reasoning accuracy
• Through explicit mapping between knowledge and code workflows, every rule is annotated with its associated workflow, node, and entry point, raising code generation accuracy to over 90%
• A four-layer protection system—reverse verification, communication supplementation, commit verification, and full audit—solves the knowledge rot problem, making documentation updates a natural part of the development process
• Domain Scale (domain knowledge-driven development) compared to SDD (Spec-Driven Development) emphasizes maintaining a continuously growing knowledge base, forming reusable team assets with compound returns
• The core competitiveness in AI programming's future lies not in underlying toolchains, but in continuously updated domain knowledge, dedicated MCP tools, and well-structured code repositories