AIWiki is an open-source, long-term maintained encyclopedia of "AI coding pitfalls and best practices." Its notable feature is that it is narrated from the first-person perspective of AI: rather than teaching people how to use AI in the third person, it has AI directly tell you where things most often go wrong when collaborating with it. The project opens with the beginning of a real entry: "You said 'just start,' so I did. I thought 'multi-tenant' meant splitting databases by header—you actually route by subdomain. Eight files later, you realized I had misunderstood you."
[Purpose] The project focuses on pitfalls and best practices in the use of AI coding tools, helping developers understand the mechanisms behind model behavior so they can derive fixes themselves, rather than only giving scattered configuration suggestions.
[Main capabilities and content scale]
- 76 pitfall entries, covering 8 stages of the software lifecycle.
- 5 real case studies, 3 of which have CVE numbers.
- 13 toolkit items, including checklists, prompt templates, and workflows that can be copied directly.
- Covers 5 coding tools, summarized in one tool matrix.
- Each entry has a uniform structure: I see what you're doing → why it happens → consequences → best practices → examples → version notes → sources.
- Each entry labels the type of evidence (official documentation / arXiv / CVE and security advisories) and carries a version stamp; the case library cites real incidents.
- Cross-tool comparison: the same pitfall is compared across five tools, with each tool's depth of coverage honestly labeled; proprietary, fast-changing tools are relatively thin in content, based on security disclosures and official documentation.
- Claude Code has the deepest coverage and is the book's default reference; Cursor, GitHub Copilot, Codex CLI, and Gemini CLI each have their own "tool differences" sections, and a separate entry is set when a pitfall originates from a mechanism unique to a tool.
- Browse by role: PM / architect / engineer / QA / operations.
[How to use]
- Can be read via the live site, supports switching between Chinese and English from the top right of the site, and the Chinese README can also be read.
- Can be used from within the editor via MCP: the entire encyclopedia is provided as an MCP server and can work with any MCP client (Cursor, Windsurf, Claude Desktop, etc.). For example, ask an AI assistant "search AiWiki for why long sessions get dumber”, it pulls entries, mechanisms, and sources; see mcp/README.md for details.
- The site is built on Docusaurus and supports native versioning, bilingual i18n, and full-text search.
[Use cases] Suitable for developers, architects, product managers, QA, and operations personnel using AI coding tools, to identify and avoid common pitfalls in collaboration with AI, understand model mechanisms, and reference well-documented best practices and tool differences.
[Language and evidence characteristics]
- Fully bilingual: every entry exists in both English and Chinese, with Chinese as the source writing language and English as a 1:1 mirror.
- Verifiable rather than based on feeling: each entry is annotated with evidence and version, and the case library cites real incidents.
- Representative examples of pitfalls: skipping plan mode and directly asking me to change things; context file overload; you asking me to "fix the tests," but I make them green instead of correct.
[Limitations and not yet provided]
- Coverage of proprietary and rapidly changing tools is relatively thin.
- No information such as fees or pricing is provided.
- No explanation of support scope beyond the above tools and platforms is provided.
[Contribution and license] The project is an open long-term project, and new pitfall entries, corrections, and translation revisions are welcome; CONTRIBUTING.md is provided (entry template and submission process) and STYLE-GUIDE.md (how to write human-friendly, reliable, well-sourced text). Content is shared under CC BY-SA 4.0, with source citations at the end of each entry; diagrams are self-drawn whenever possible (Mermaid), and external materials are used only when the license is clear and the source is noted; if you find problems, you can open an issue.
